devflow-kit 1.8.3 → 2.0.0

package/src/assets/skills/dependencies/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: dependencies
+description: This skill should be used when reviewing dependency changes, lock files, or package additions.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Dependencies Patterns
+
+Domain expertise for dependency management and security analysis. Use alongside `devflow:review-methodology` for complete dependency reviews.
+
+## Iron Law
+
+> **EVERY DEPENDENCY IS AN ATTACK SURFACE**
+>
+> Each package you add is code you didn't write but must trust. Minimize dependencies.
+> Pin versions. Audit regularly. A single compromised transitive dependency can compromise
+> your entire application. "It's a popular package" is not a security review.
+
+---
+
+## Dependency Categories
+
+### 1. Security Vulnerabilities
+
+Known CVEs, vulnerable version ranges, malicious packages.
+
+**Violation**: Wide version range includes vulnerable versions
+```json
+{ "lodash": "^4.0.0" }  // Includes vulnerable 4.17.0-4.17.20
+```
+
+**Correct**: Pin to safe version
+```json
+{ "lodash": "^4.17.21" }  // First safe version
+```
+
+### 2. Version Management
+
+Unpinned versions, missing lockfiles, dependency conflicts.
+
+**Violation**: Unpinned allows any version
+```json
+{ "express": "*", "lodash": "latest" }
+```
+
+**Correct**: Pin with lockfile
+```json
+{ "express": "^4.18.2" }  // + committed lockfile
+```
+
+### 3. Dependency Health
+
+Outdated packages, unused dependencies, unnecessary heavy packages.
+
+**Violation**: Heavy dependency for simple task
+```json
+{ "moment": "^2.29.4" }  // 300KB for date formatting
+```
+
+**Correct**: Use native or lighter alternative
+```typescript
+new Date().toLocaleDateString();  // Native
+```
+
+### 4. License Issues
+
+Incompatible licenses (GPL in MIT project), missing licenses.
+
+**Violation**: GPL in proprietary code
+```bash
+# GPL-3.0: some-package  # Requires your code to be GPL too!
+```
+
+**Correct**: Use permissive licenses only
+```bash
+npx license-checker --failOn "GPL-3.0;AGPL-3.0"
+```
+
+### 5. Supply Chain Risks
+
+Deep transitive dependencies, unmaintained packages, typosquatting.
+
+**Violation**: Typosquatted package
+```json
+{ "loadsh": "1.0.0" }  // Typosquat of "lodash"
+```
+
+**Correct**: Verify package authenticity
+```bash
+npm view loadsh  # Check downloads, repo, maintainers
+```
+
+---
+
+## Extended References
+
+For extended examples and detection commands, see:
+- `references/violations.md` - Extended violation examples by category
+- `references/patterns.md` - Correct dependency management patterns
+- `references/detection.md` - Detection commands and CI integration
+
+---
+
+## Severity Guidelines
+
+| Severity | Indicators |
+|----------|------------|
+| **CRITICAL** | Known exploited CVEs (CISA KEV), confirmed malicious packages, typosquats |
+| **HIGH** | High severity CVEs, unmaintained packages, GPL in proprietary code |
+| **MEDIUM** | Medium CVEs, significantly outdated, wide version ranges, missing lockfile |
+| **LOW** | Unused dependencies, lighter alternatives available, minor version behind |
+
+---
+
+## Dependency Review Checklist
+
+Before approving dependency changes:
+
+- [ ] No known CVEs in added packages
+- [ ] Version ranges appropriate (not too wide)
+- [ ] Lockfile updated and committed
+- [ ] Package actively maintained
+- [ ] License compatible
+- [ ] Package from verified publisher
+- [ ] Transitive dependencies reviewed
+- [ ] Package name verified (not typosquat)
+- [ ] Bundle size impact considered
+- [ ] Native alternatives considered
+
+---
+
+## Common Vulnerability Sources
+
+| Registry | URL |
+|----------|-----|
+| npm Advisory | https://www.npmjs.com/advisories |
+| Snyk Vuln DB | https://snyk.io/vuln |
+| GitHub Advisory | https://github.com/advisories |
+| NVD | https://nvd.nist.gov/ |
+| CISA KEV | https://www.cisa.gov/known-exploited-vulnerabilities-catalog |

package/src/assets/skills/dependency-research/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: dependency-research
+description: >-
+  This skill should be used when the user asks to "add a utility", "create a helper",
+  "implement parsing", "build a wrapper", or writes infrastructure/utility code that
+  may already exist as a well-maintained package. Enforces research before building.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Research
+
+Research before building. Check if a battle-tested solution exists before writing custom utility code.
+
+## Iron Law
+
+> **RESEARCH BEFORE BUILDING**
+>
+> Never write custom utility code without first checking if a battle-tested solution
+> exists. The best code is code you don't write. A maintained package with thousands
+> of users will always beat a hand-rolled utility in reliability, edge cases, and
+> long-term maintenance.
+
+## When This Skill Activates
+
+**Triggers** — creating or modifying code that:
+- Parses, formats, or validates data (dates, URLs, emails, UUIDs, etc.)
+- Implements common algorithms (sorting, diffing, hashing, encoding)
+- Wraps HTTP clients, retries, rate limiting, caching
+- Handles file system operations beyond basic read/write
+- Implements CLI argument parsing, logging, or configuration
+- Creates test utilities (mocking, fixtures, assertions)
+
+**Does NOT trigger** for:
+- Domain-specific business logic unique to this project
+- Glue code connecting existing components
+- Trivial operations (< 5 lines, single-use)
+- Code that intentionally avoids external dependencies (e.g., zero-dep libraries)
+
+---
+
+## Research Process
+
+### Phase 1: Need Analysis
+
+Before searching, define what you actually need:
+
+```
+Need: {one-sentence description of the capability}
+Constraints: {runtime, bundle size, license, zero-dep requirement}
+Must-haves: {non-negotiable requirements}
+Nice-to-haves: {optional features}
+```
+
+### Phase 2: Search
+
+Delegate research to an Explore subagent to keep main session context clean.
+
+**Spawn an Explore agent** with this prompt template:
+
+```
+Agent(subagent_type="Explore"):
+"Research existing solutions for: {need description}
+
+Search for:
+1. npm/PyPI/crates packages that solve this (check package.json/requirements.txt for ecosystem)
+2. Existing utilities in this codebase (grep for related function names)
+3. Framework built-ins that already handle this
+
+For each candidate, find:
+- Package name and weekly downloads (if applicable)
+- Last publish date and maintenance status
+- Bundle size / dependency count
+- API surface relevant to our need
+- License compatibility
+
+Return top 3 candidates with pros/cons, or confirm nothing suitable exists."
+```
+
+### Phase 3: Evaluate
+
+Score each candidate against evaluation criteria. See `references/evaluation-criteria.md` for the full matrix.
+
+Quick checklist:
+- [ ] Last published within 12 months
+- [ ] Weekly downloads > 1,000 (npm) or equivalent traction
+- [ ] No known vulnerabilities (check Snyk/npm audit)
+- [ ] API fits the use case without heavy wrapping
+- [ ] License compatible with project (MIT/Apache/BSD preferred)
+- [ ] Bundle size acceptable for the project context
+
+### Phase 4: Decide
+
+Choose one of four outcomes:
+
+| Decision | When | Action |
+|----------|------|--------|
+| **Adopt** | Exact match, well-maintained, good API | Install and use directly |
+| **Extend** | Partial match, needs thin wrapper | Install + write minimal adapter |
+| **Compose** | No single package fits, but 2-3 small ones combine well | Install multiple, write glue code |
+| **Build** | Nothing fits, or dependency cost exceeds value | Write custom, document why |
+
+**Document the decision** in a code comment at the usage site:
+
+```typescript
+// research: Adopted date-fns for date formatting (2M weekly downloads, 30KB)
+// research: Built custom — no package handles our specific wire format
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|-------------|-----------------|
+| Adding a dependency for 5 lines of trivial code | Build — dependency overhead exceeds value |
+| Choosing the most popular package without checking fit | Evaluate API fit, not just popularity |
+| Wrapping a package so heavily it obscures the original | If wrapping > 50% of original API, reconsider |
+| Skipping research because "I know how to build this" | Research anyway — maintenance cost matters more than initial build |
+| Installing a massive framework for one utility function | Look for focused, single-purpose packages |
+
+## Scope Limiter
+
+This skill concerns **utility and infrastructure code** only:
+- Data transformation, validation, formatting
+- Network operations, retries, caching
+- CLI tooling, logging, configuration
+- Test utilities and helpers
+
+It does NOT apply to **domain-specific business logic** where:
+- The logic encodes unique business rules
+- No generic solution could exist
+- The code is inherently project-specific

package/src/assets/skills/dependency-research/references/evaluation-criteria.md

@@ -0,0 +1,101 @@
+# Search-First — Evaluation Criteria
+
+Detailed package evaluation criteria and decision matrix for the 4-outcome model.
+
+## Evaluation Matrix
+
+Score each candidate on these axes (1-5 scale):
+
+| Criterion | Weight | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
+|-----------|--------|-----------|-----------------|----------------|
+| **Maintenance** | High | No commits in 2+ years | Active, yearly releases | Regular releases, responsive maintainer |
+| **Adoption** | Medium | < 100 weekly downloads | 1K-10K weekly downloads | > 100K weekly downloads |
+| **API Fit** | High | Needs heavy wrapping | Partial fit, thin adapter needed | Direct use, clean API |
+| **Bundle Size** | Medium | > 500KB | 50-500KB | < 50KB |
+| **Security** | High | Known vulnerabilities | No known issues, few dependencies | Audited, zero/minimal dependencies |
+| **License** | Required | GPL/AGPL (restrictive) | LGPL (conditional) | MIT/Apache/BSD (permissive) |
+
+**Minimum thresholds**: License must be compatible. Security must be ≥ 3. All others are trade-offs.
+
+## Decision Matrix
+
+### Adopt (score ≥ 20/25, API Fit ≥ 4)
+
+The package directly solves the problem with minimal integration code.
+
+**Example**: Using `zod` for schema validation — exact fit, massive adoption, tiny bundle.
+
+```
+✅ Adopt: zod v3.22
+- Maintenance: 5 (monthly releases)
+- Adoption: 5 (4M weekly downloads)
+- API Fit: 5 (direct use for all validation)
+- Bundle Size: 4 (57KB)
+- Security: 5 (zero dependencies)
+- Total: 24/25
+```
+
+### Extend (score ≥ 15/25, API Fit ≥ 2)
+
+The package handles 60-80% of the need. Write a thin adapter for the rest.
+
+**Example**: Using `got` for HTTP but wrapping it with project-specific retry and auth logic.
+
+```
+✅ Extend: got v14
+- Maintenance: 4 (active)
+- Adoption: 5 (8M weekly downloads)
+- API Fit: 3 (need custom retry wrapper)
+- Bundle Size: 3 (150KB)
+- Security: 4 (minimal deps)
+- Total: 19/25
+Adapter: ~30 lines wrapping retry + auth headers
+```
+
+### Compose (no single package fits, but small packages combine)
+
+Two or three focused packages together solve the problem better than one large framework.
+
+**Example**: `ms` (time parsing) + `p-retry` (retry logic) + `quick-lru` (caching) instead of a monolithic HTTP client framework.
+
+**Rules for Compose**:
+- Maximum 3 packages in a composition
+- Each package must be focused (single responsibility)
+- Total combined bundle < what a monolithic alternative would cost
+- Glue code should be < 50 lines
+
+### Build (nothing fits, or dependency cost > value)
+
+Write custom code when:
+- No package scores ≥ 15/25
+- The code is < 50 lines and trivial
+- Zero-dependency constraint is explicit
+- The domain is too specific for generic packages
+
+**Required**: Document why Build was chosen:
+
+```typescript
+// research: Built custom — our wire format uses non-standard
+// ISO-8601 extensions that no date library handles correctly.
+// Evaluated: date-fns (no custom format support), luxon (500KB overhead),
+// dayjs (close but missing timezone edge case).
+```
+
+## Ecosystem-Specific Hints
+
+### Node.js / TypeScript
+- Check npm: `https://www.npmjs.com/package/{name}`
+- Bundle size: `https://bundlephobia.com/package/{name}`
+- Check if Node.js built-ins handle it (`node:crypto`, `node:url`, `node:path`)
+
+### Python
+- Check PyPI: `https://pypi.org/project/{name}`
+- Check if stdlib handles it (`urllib`, `json`, `pathlib`, `dataclasses`)
+
+### Rust
+- Check crates.io: `https://crates.io/crates/{name}`
+- Check if std handles it
+
+### Go
+- Check pkg.go.dev
+- Go standard library is extensive — check stdlib first

package/src/assets/skills/design-review/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: design-review
+description: This skill should be used when reviewing implementation plans for anti-patterns, checking design quality before implementation, or performing plan-level quality assessment. Provides 6 anti-pattern detection rules for the Design agent and inline planning.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Design Review
+
+Anti-pattern detection for implementation plans. Catches structural problems before they become code.
+
+## Iron Law
+
+> **CATCH IT IN THE PLAN, NOT IN THE PR**
+>
+> A plan that implies N+1 queries will produce N+1 queries. A plan that omits error
+> handling will produce code with no error handling. Review the plan as rigorously as
+> you review the code — the plan is the blueprint that every implementation decision
+> follows.
+
+---
+
+## Anti-Pattern Detection Rules
+
+### 1. N+1 Queries
+
+**What to look for in a plan:**
+- Steps that fetch a list, then loop to fetch related data per item
+- "For each X, get Y" language without mentioning batch operations
+- JOIN or batch-fetch never mentioned for related data
+- "Display X with Y" without specifying how Y is fetched
+
+**How to flag:**
+```
+[N+1 RISK] Step {N}: "{quoted plan text}" — fetches {entity} per iteration.
+Resolution: Replace loop with batch query: {proposed batch operation}.
+```
+
+**What to suggest instead:**
+- Identify all IDs in the list first, then batch-fetch related records in one query
+- Use ORM eager loading (`.include`, `.with`, JOIN) at the list query level
+- Cache frequently accessed related data at the service layer
+
+### 2. God Functions
+
+**What to look for in a plan:**
+- Single step handling more than 3 distinct responsibilities
+- "Validate AND process AND notify AND log AND update" in one step
+- Steps described as "the main handler" that touch multiple subsystems
+- No clear single-sentence description of what the function does
+
+**How to flag:**
+```
+[GOD FUNCTION RISK] Step {N}: "{quoted plan text}" — handles {n} responsibilities.
+Resolution: Split into: {responsibility 1} → {responsibility 2} → {responsibility 3}.
+```
+
+**What to suggest instead:**
+- Each function should have a single, clear sentence description of its purpose
+- Extract notification, logging, and side effects to separate functions
+- Orchestrate composition at a higher level (service layer calls multiple focused functions)
+
+### 3. Missing Parallelism
+
+**What to look for in a plan:**
+- Sequential steps with no data dependency between them
+- "First do A, then do B, then do C" where B doesn't need A's output
+- Multiple external API calls or DB queries listed sequentially
+- Fan-out operations (notify all users, update all records) without parallel mention
+
+**How to flag:**
+```
+[SEQUENTIAL BOTTLENECK] Steps {N}-{M}: "{quoted steps}" — no dependency between them.
+Resolution: Execute {step A} and {step B} in parallel: {proposed parallel pattern}.
+```
+
+**What to suggest instead:**
+- Use `Promise.all` / goroutines / async.gather for independent operations
+- Identify the critical path and move independent work off it
+- Explicitly note which steps have ordering requirements vs. which are independent
+
+### 4. Error Handling Gaps
+
+**What to look for in a plan:**
+- Happy path fully described, failure paths absent or vague
+- "If error, return error" without specifying what the caller does with it
+- Partial operations (multi-step) without rollback plan
+- External calls (API, DB, queue) without failure mode specification
+- Retry logic absent for transient failures (network timeouts, rate limits)
+
+**How to flag:**
+```
+[ERROR HANDLING GAP] Step {N}: "{quoted plan text}" — failure path unspecified.
+Resolution: Add: {on failure scenario} → {specific recovery action}.
+```
+
+**What to suggest instead:**
+- For each external call, specify: what to do on timeout, on 4xx, on 5xx
+- For multi-step operations, specify compensation (rollback/undo) for each step
+- Use Result types or explicit error returns — no silent failures
+
+### 5. Missing Caching
+
+**What to look for in a plan:**
+- Expensive operations called on every request without cache mention
+- "Fetch configuration on each request", "call third-party API per user action"
+- Reference data (categories, settings, permissions) loaded repeatedly
+- Computed aggregates recalculated on every read
+
+**How to flag:**
+```
+[CACHING GAP] Step {N}: "{quoted plan text}" — {expensive operation} on every request.
+Resolution: Cache {data} for {TTL}: {proposed cache strategy and invalidation}.
+```
+
+**What to suggest instead:**
+- Application-level cache (Redis/Memcached) for cross-request data
+- In-memory cache for process-local reference data with short TTL
+- Specify cache invalidation: event-driven (on update), time-based (TTL), or both
+
+### 6. Poor Decomposition
+
+**What to look for in a plan:**
+- Steps combining unrelated concerns (auth + business logic + presentation)
+- Unclear ownership — which module/layer owns each step?
+- Cross-cutting steps that appear multiple times without abstraction
+- "Also update X" or "also send to Y" appended to otherwise focused steps
+
+**How to flag:**
+```
+[DECOMPOSITION ISSUE] Step {N}: "{quoted plan text}" — combines {concern A} and {concern B}.
+Resolution: {concern A} belongs in {layer/module}; {concern B} belongs in {layer/module}.
+```
+
+**What to suggest instead:**
+- Assign each step to exactly one layer: presentation, business logic, data access
+- Extract cross-cutting concerns (logging, auth, validation) to middleware or decorators
+- Each module should have a clear bounded context — changes to one shouldn't require changes to another
+
+---
+
+## Extended References
+
+| Reference | Content |
+|-----------|---------|
+| `references/anti-patterns.md` | Before/after plan examples for each anti-pattern |
+
+## Severity Guidelines
+
+| Level | Criteria |
+|-------|----------|
+| **CRITICAL** | Anti-pattern that will cause correctness failures (data loss, security breach) |
+| **HIGH** | Anti-pattern that will cause significant performance or maintainability problems |
+| **MEDIUM** | Anti-pattern that will require architectural rework post-implementation |
+| **LOW** | Anti-pattern that reduces code quality but is easily refactored |