devflow-kit 3.11.0 → 3.12.1

package/src/assets/skills/dependencies/references/detection.md

@@ -179,3 +179,13 @@ audit_deps() {
 | Licenses | `npx license-checker` |
 | Tree depth | `npm ls --all \| wc -l` |
 | Lockfile | `ls package-lock.json yarn.lock 2>/dev/null` |
+
+## 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

@@ -20,7 +20,7 @@ Research before building. Check if a battle-tested solution exists before writin
 
 ## When This Skill Activates
 
-**Triggers** — creating or modifying code that:
+**Triggers** — creating or modifying utility or infrastructure 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
@@ -28,51 +28,21 @@ Research before building. Check if a battle-tested solution exists before writin
 - 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
+**Does not trigger** for:
+- Domain-specific business logic unique to this project, where no generic solution could exist
 - 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}
-```
+Before searching, write the need in one sentence, with its constraints (runtime, bundle size, license, zero-dep requirement), its must-haves and its nice-to-haves.
 
 ### Phase 2: Search
 
-Spawn an Explore subagent when you can spawn agents, to keep main session context clean; otherwise search directly, using the template's questions as your checklist.
-
-**Prompt template** for the Explore agent:
-
-```
-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."
-```
+Spawn an Explore subagent when you can spawn agents, to keep main session context clean; otherwise search directly. Search for packages in the project's ecosystem (npm/PyPI/crates; check package.json/requirements.txt), existing utilities in this codebase, and framework built-ins. For each candidate, find weekly downloads, last publish date and maintenance status, bundle size and dependency count, the API surface relevant to the need, and license. Return the top 3 candidates with pros and cons, or confirm nothing suitable exists.
 
 ### Phase 3: Evaluate
 
@@ -97,34 +67,10 @@ Choose one of four outcomes:
 | **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
-```
-
----
+**Document the decision** in a code comment at the usage site, for example `// research: Adopted date-fns for date formatting (2M weekly downloads, 30KB)` or `// 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
+- 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 the original API, reconsider.
+- Installing a massive framework for one utility function: look for focused, single-purpose packages.

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

@@ -1,13 +1,13 @@
 ---
 name: design-review
-description: This skill should be used when reviewing implementation plans for anti-patterns.
+description: Use when reviewing implementation plans for anti-patterns.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 ---
 
 # Design Review
 
-Anti-pattern detection for implementation plans. Catches structural problems before they become code.
+Anti-pattern detection for implementation plans.
 
 ## Iron Law
 
@@ -15,10 +15,7 @@ Anti-pattern detection for implementation plans. Catches structural problems bef
 >
 > 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.
-
----
+> the code: every implementation decision follows it.
 
 ## Anti-Pattern Detection Rules
 
@@ -36,10 +33,7 @@ Anti-pattern detection for implementation plans. Catches structural problems bef
 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
+**Suggest:** collect the IDs first and batch-fetch the related rows in one query, or eager-load them (JOIN) in the list query.
 
 ### 2. God Functions
 
@@ -55,10 +49,7 @@ Resolution: Replace loop with batch query: {proposed batch operation}.
 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)
+**Suggest:** one purpose per function; move notification, logging and other side effects to their own functions, and compose them at the service layer.
 
 ### 3. Missing Parallelism
 
@@ -74,10 +65,7 @@ Resolution: Split into: {responsibility 1} → {responsibility 2} → {responsib
 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
+**Suggest:** run independent steps in parallel (`Promise.all`, goroutines, `asyncio.gather`), and name the steps that must stay in order.
 
 ### 4. Error Handling Gaps
 
@@ -94,10 +82,7 @@ Resolution: Execute {step A} and {step B} in parallel: {proposed parallel patter
 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
+**Suggest:** for each external call, the action on timeout, 4xx and 5xx; a compensation step for each step of a multi-step operation; Result types or explicit error returns, never a silent failure.
 
 ### 5. Missing Caching
 
@@ -113,10 +98,7 @@ Resolution: Add: {on failure scenario} → {specific recovery action}.
 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
+**Suggest:** an application cache for cross-request data, a short-TTL in-memory cache for process-local reference data, and the invalidation (on update, by TTL, or both).
 
 ### 6. Poor Decomposition
 
@@ -132,12 +114,7 @@ Resolution: Cache {data} for {TTL}: {proposed cache strategy and invalidation}.
 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
-
----
+**Suggest:** one layer per step (presentation, business logic, data access); cross-cutting concerns (logging, auth, validation) in middleware or decorators; one bounded context per module.
 
 ## Extended References
 
@@ -147,9 +124,9 @@ Resolution: {concern A} belongs in {layer/module}; {concern B} belongs in {layer
 
 ## Severity Guidelines
 
-| Level | Criteria |
+| Level | An anti-pattern that |
 |-------|----------|
-| **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 |
+| **CRITICAL** | will cause correctness failures (data loss, security breach) |
+| **HIGH** | will cause significant performance or maintainability problems |
+| **MEDIUM** | will require architectural rework post-implementation |
+| **LOW** | reduces code quality but is easily refactored |

package/src/assets/skills/docs-framework/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-framework
-description: This skill should be used when creating files in the .devflow/docs/ directory.
+description: Use when creating files in the .devflow/docs/ directory.
 user-invocable: false
 allowed-tools: Read, Bash, Glob
 ---
@@ -16,10 +16,7 @@ The canonical source for what Devflow names under `.devflow/docs/`. A command th
 > A run directory is `YYYY-MM-DD_HHMM` in local time; a second run in the same minute takes
 > seconds (`YYYY-MM-DD_HHMMSS`). Branch slugs replace `/` with `-`. Topic slugs are lowercase
 > alphanumeric with single dashes, at most 50 characters. The exceptions are the ones listed
-> under Naming Conventions, and no others. Inconsistent naming breaks tooling, searching, and
-> automation. Follow the pattern or fix the pattern for everyone.
-
----
+> under Naming Conventions, and no others. Follow the pattern or fix the pattern for everyone.
 
 ## Directory Structure
 
@@ -74,26 +71,18 @@ All generated documentation lives under `.devflow/docs/` at the checkout's tople
 
 The head markers for incremental runs are not part of this tree. `/code-review` and `/bug-analysis` keep each one under the git directory of the worktree, at `<git dir>/devflow/reviews/{branch-slug}/.last-review-head` and `<git dir>/devflow/bug-analysis/{branch-slug}/.last-analysis-head`. `<git dir>` is the path that `git rev-parse --absolute-git-dir` prints, so each worktree has its own markers.
 
----
-
 ## Naming Conventions
 
 ### Timestamps
 
-`YYYY-MM-DD_HHMM`, local time (sortable, readable), computed once per run and reused for every path of that run:
-```bash
-TIMESTAMP=$(date +%Y-%m-%d_%H%M)  # Example: 2025-12-26_1430
-```
+`YYYY-MM-DD_HHMM`, local time (sortable, readable), computed once per run and reused for every path of that run.
 - **Same-minute collision.** `/code-review`, `/bug-analysis` and `/research` create their run directory themselves: when it already exists, the second run appends seconds (`2025-12-26_143005`). It sorts after its minute, so newest-first listings stay correct.
 - **Workflow runs** (`tickets/`, `design/{slug}/`, `waves/`) are stamped in local time by the workflow that creates them and take no collision suffix: a second run in the same minute writes into the first's directory.
 - A design document's timestamp is the suffix before `.md`, so a listing sorts by that suffix, not by the leading `{ISSUE_ID}`.
 
 ### Branch Slugs
 
-The branch name with every `/` replaced by `-`; case, dots and underscores are kept. A detached HEAD has no name and uses `standalone`:
-```bash
-BRANCH_SLUG=$(b=$(git branch --show-current 2>/dev/null); echo "${b:-standalone}" | sed 's/\//-/g')
-```
+The branch name with every `/` replaced by `-`; case, dots and underscores are kept. A detached HEAD has no name and uses `standalone`.
 A slug builds a path or reaches a shell only when it matches `^[A-Za-z0-9._-]{1,200}$`. Every command derives `{branch_slug}` (the underscore spelling in `handoff-*` and `evidence-*`) this way, from the branch the work is on.
 
 ### Topic Slugs
@@ -114,16 +103,8 @@ TOPIC_SLUG=$(s=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9
 | Type | Pattern | Example |
 |------|---------|---------|
 | Special indexes | `UPPERCASE.md` | `WORKING-MEMORY.md`, `INDEX.md` |
-| Reports and summaries | `{focus}.md`, `review-summary.md`, `bug-analysis-summary.md`, `research-summary.md`, `static-findings.md`, `resolution-summary.md` in the run directory | `2025-12-26_1430/security.md` |
-| Head markers | `<git dir>/devflow/reviews/{branch-slug}/.last-review-head`, `<git dir>/devflow/bug-analysis/{branch-slug}/.last-analysis-head` | Plain text file with SHA |
 | Status logs | `{timestamp}.md` | `2025-12-26_1430.md` |
 | Design documents | `{ISSUE_ID}-{topic-slug}.{timestamp}.md` | `42-jwt-auth.2026-04-07_1430.md` |
-| Design (several issues) | `multi-{topic-slug}.{timestamp}.md` | `multi-jwt-auth.2026-04-07_1430.md` |
-| Design (no issue) | `{topic-slug}.{timestamp}.md` | `jwt-auth.2026-04-07_1430.md` |
-| Per-ticket plan | `{ticket-slug}-plan.md` in `design/{slug}/{timestamp}/` | `design/wave/2026-04-07_1430/add-login-plan.md` |
-| Handoff, evidence | `handoff-{branch-slug}.md`, `evidence-{branch-slug}.md`, `evidence-wave-{slug}.md` | `evidence-feat-jwt-auth.md` |
-
----
 
 ## Helper Functions
 
@@ -138,8 +119,6 @@ get_docs_root() { git rev-parse --show-toplevel 2>/dev/null || pwd; }
 ensure_docs_dir() { mkdir -p "$(get_docs_root)/.devflow/docs/$1"; }
 ```
 
----
-
 ## Agent Persistence Rules
 
 ### Who Writes What
@@ -156,36 +135,14 @@ ensure_docs_dir() { mkdir -p "$(get_docs_root)/.devflow/docs/$1"; }
 - Git (fetch-issue: read-only, post-review-summary: consolidated review comment only)
 - Code agent (commits to git; its only file is the handoff section it appends when `HANDOFF_FILE` is given)
 
----
-
 ## Implementation Checklist
 
 When creating or modifying persisting agents or commands:
 
-- [ ] Use the run-directory timestamp (`YYYY-MM-DD_HHMM`, local time, seconds on a same-minute collision)
-- [ ] Derive the branch slug (replace `/` with `-`) and gate it before it builds a path
-- [ ] Derive topic slugs with the one rule (lowercase, single dashes, at most 50)
-- [ ] Create directory with `mkdir -p .devflow/docs/{subdir}`
 - [ ] Document output location in agent's final message
-- [ ] Follow special file naming (UPPERCASE for indexes)
-- [ ] Use helper functions when possible
 - [ ] Update relevant index files
 
----
-
-## Integration
-
-This framework is used by:
-- **`/plan` and `/research`**: load it at the step that names the document, and build the path by its rules
-- **Commands that hand paths to agents** (`/code-review`, `/bug-analysis`, `/implement`, `/resolve`, the `/dynamic-*` commands): follow it, with the exceptions above
-- **Working Memory hooks**: Auto-maintains `.devflow/memory/WORKING-MEMORY.md`
-- **Curate agent**: background LLM agent (spawned via the session-start directive) promotes observations to ADRs/PFs via `assign-anchor`, which renders `decisions.md` / `pitfalls.md`
-
----
-
 ## Extended References
 
-For detailed patterns and violation examples:
-
 - **[patterns.md](./references/patterns.md)** - Full templates, helper functions, naming examples, edge cases
 - **[violations.md](./references/violations.md)** - Common violations with detection patterns and fixes

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

@@ -1,24 +1,22 @@
 ---
 name: documentation
-description: This skill should be used when reviewing for documentation drift or stale comments.
+description: Use when reviewing for documentation drift or stale comments.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 ---
 
 # Documentation Patterns
 
-Domain expertise for documentation quality and alignment. Use alongside `devflow:review-methodology` for complete documentation reviews.
+Detection patterns for documentation quality and alignment review. Use with `devflow:review-methodology`.
 
 ## Iron Law
 
-> **DOCUMENTATION MUST MATCH REALITY**
+> **Documentation must match reality.**
 >
 > Outdated documentation is worse than no documentation. It actively misleads. Every code
 > change that affects behavior requires a documentation check. Comments that explain "what"
 > instead of "why" are noise. The best documentation is code that doesn't need documentation.
 
----
-
 ## Documentation Categories
 
 ### 1. Code Documentation Issues
@@ -30,20 +28,7 @@ Domain expertise for documentation quality and alignment. Use alongside `devflow
 | "What" comments | `// Loop through users` | Explain "why" instead |
 | Magic algorithms | Complex logic without explanation | Document algorithm and rationale |
 | Transition residue | "We no longer do X" notes, in-file changelogs, or refs to removed code/sections | Remove — git holds the history |
-
-**Brief Example - Missing vs. Complete:**
-```typescript
-// BAD: No documentation on complex function
-export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
-
-// GOOD: Purpose, params, returns, edge cases documented
-/**
- * Calculates prorated billing amount when switching plans mid-cycle.
- * @param plan - The new plan to prorate to
- * @returns Prorated amount in cents (can be negative for downgrades)
- */
-export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
-```
+| Stale TODOs | TODO comments for completed work | Remove |
 
 ### 2. API Documentation Issues
 
@@ -53,22 +38,6 @@ export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Da
 | Missing returns | Return shape unknown | Describe return structure and units |
 | Missing errors | Callers don't know what to catch | List all thrown error types |
 
-**Brief Example - Incomplete vs. Complete:**
-```typescript
-// BAD: No params, no errors documented
-/** Creates a subscription. */
-async function createSubscription(userId: string, planId: string): Promise<Subscription>;
-
-// GOOD: Full contract documented
-/**
- * @param userId - User's unique identifier
- * @param planId - Plan ID from /plans endpoint
- * @throws {UserNotFoundError} If userId doesn't exist
- * @throws {PlanNotFoundError} If planId doesn't exist
- */
-async function createSubscription(userId: string, planId: string): Promise<Subscription>;
-```
-
 ### 3. Alignment Issues
 
 | Issue | Problem | Fix |
@@ -77,28 +46,11 @@ async function createSubscription(userId: string, planId: string): Promise<Subsc
 | Stale README | Examples use removed functions | Keep README in sync with code |
 | Missing changelog | Breaking changes undocumented | Document all notable changes |
 
-**Brief Example - Drift vs. Aligned:**
-```typescript
-// BAD: Comment doesn't match code
-// Retries up to 3 times
-for (let i = 0; i < 5; i++) { /* ... */ }
-
-// GOOD: Use constant to keep aligned
-const MAX_RETRIES = 5;
-for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }
-```
-
----
-
 ## Extended References
 
-For extended examples and detection commands:
-
-- **[references/violations.md](references/violations.md)** - Extended violation examples with explanations
-- **[references/patterns.md](references/patterns.md)** - Complete correct pattern examples
-- **[references/detection.md](references/detection.md)** - Bash commands for finding issues
-
----
+- `references/violations.md` - Extended violation examples with explanations
+- `references/patterns.md` - Complete correct pattern examples
+- `references/detection.md` - Bash commands for finding issues
 
 ## Severity Guidelines
 
@@ -108,19 +60,3 @@ For extended examples and detection commands:
 | **HIGH** | Significant gaps | Public APIs undocumented; Complex algorithms unexplained; Errors not documented; Migration guides missing |
 | **MEDIUM** | Moderate issues | Some params undocumented; Examples could be clearer; "What" comments instead of "why" |
 | **LOW** | Minor improvements | Could add more examples; Formatting inconsistencies; Typos |
-
----
-
-## Documentation Checklist
-
-Before approving changes:
-
-- [ ] All public APIs have JSDoc/docstrings
-- [ ] Parameters and return values documented
-- [ ] Error conditions documented
-- [ ] Complex algorithms explained
-- [ ] Comments explain "why", not "what"
-- [ ] README reflects current state
-- [ ] CHANGELOG updated for notable changes
-- [ ] No TODO comments for completed work
-- [ ] Examples work with current API

package/src/assets/skills/documentation/references/patterns.md

@@ -1,6 +1,6 @@
 # Correct Documentation Patterns
 
-Extended examples of proper documentation. See parent `SKILL.md` for brief examples and severity guidelines.
+Extended examples of proper documentation. See parent `SKILL.md` for the rules and severity guidelines.
 
 ---
 

package/src/assets/skills/documentation/references/violations.md

@@ -1,6 +1,6 @@
 # Documentation Violation Examples
 
-Extended examples of documentation anti-patterns. See parent `SKILL.md` for brief examples and severity guidelines.
+Extended examples of documentation anti-patterns. See parent `SKILL.md` for the rules and severity guidelines.
 
 ---