npm - devflow-kit - Versions diffs - 1.8.3 → 2.0.1 - Mend

devflow-kit 1.8.3 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (867) hide show

package/shared/skills/docs-framework/references/patterns.md DELETED Viewed

@@ -1,346 +0,0 @@
-# Documentation Framework Patterns
-Correct patterns for DevFlow documentation artifacts with templates and helper functions.
----
-## Directory Structure
-### Standard Layout
-```
-.docs/
-├── reviews/{branch-slug}/          # Code review reports per branch
-│   ├── {type}-report.{timestamp}.md
-│   └── review-summary.{timestamp}.md
-├── design/                         # Implementation plans
-│   └── {topic-slug}.{timestamp}.md
-├── status/                         # Development logs
-│   ├── {timestamp}.md
-│   ├── compact/{timestamp}.md
-│   └── INDEX.md
-└── CATCH_UP.md                     # Latest summary (overwritten)
-```
-### Setup Variations
-**Minimal (new project):**
-```
-.docs/
-├── status/
-│   └── INDEX.md
-└── CATCH_UP.md
-```
-**With Reviews:**
-```
-.docs/
-├── reviews/feat-auth/
-│   ├── security-report.2025-01-05_1430.md
-│   └── review-summary.2025-01-05_1430.md
-├── status/
-│   ├── 2025-01-05_1430.md
-│   └── INDEX.md
-└── CATCH_UP.md
-```
----
-## Naming Conventions
-### Timestamps
-Format: `YYYY-MM-DD_HHMM` (sortable, readable)
-```bash
-# Standard format
-TIMESTAMP=$(date +%Y-%m-%d_%H%M)
-# Output: 2025-01-05_1430
-# With seconds (only if needed for uniqueness)
-TIMESTAMP_SEC=$(date +%Y-%m-%d_%H%M%S)
-# Output: 2025-01-05_143025
-```
-### Branch Slugs
-Replace `/` with `-`, provide fallback for detached HEAD.
-```bash
-BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
-# Examples:
-# feature/auth          -> feature-auth
-# fix/issue-123         -> fix-issue-123
-# hotfix/critical-bug   -> hotfix-critical-bug
-# release/v2.0.0        -> release-v2.0.0
-# (detached HEAD)       -> standalone
-```
-### Topic Slugs
-Lowercase, dashes, alphanumeric only, max 50 chars.
-```bash
-TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50)
-# Examples:
-# "JWT Authentication"       -> jwt-authentication
-# "Fix User Login Bug"       -> fix-user-login-bug
-# "OAuth 2.0 Integration"    -> oauth-20-integration
-# "Database Migration v2"    -> database-migration-v2
-```
----
-## File Naming Rules
-### Special Index Files (UPPERCASE)
-Always UPPERCASE, overwritten or appended:
-- `CATCH_UP.md` - Latest context summary
-- `INDEX.md` - Chronological log index
-- `KNOWLEDGE_BASE.md` - Searchable debug solutions
-### Artifact Files (lowercase + timestamp)
-Always lowercase with timestamp:
-- `2025-01-05_1430.md` - Status log
-- `security-report.2025-01-05_1430.md` - Review report
-- `review-summary.2025-01-05_1430.md` - Combined summary
-- `jwt-authentication.2025-01-05_1430.md` - Design doc
----
-## Helper Functions
-Full implementation for `.devflow/scripts/docs-helpers.sh`:
-```bash
-#!/bin/bash
-# .devflow/scripts/docs-helpers.sh
-# Get current timestamp in standard format
-get_timestamp() {
-    date +%Y-%m-%d_%H%M
-}
-# Get sanitized branch slug
-get_branch_slug() {
-    local branch
-    branch=$(git branch --show-current 2>/dev/null)
-    if [ -z "$branch" ]; then
-        echo "standalone"
-    else
-        echo "$branch" | sed 's/\//-/g'
-    fi
-}
-# Convert topic to slug format
-get_topic_slug() {
-    local topic="$1"
-    echo "$topic" | \
-        tr '[:upper:]' '[:lower:]' | \
-        tr ' ' '-' | \
-        sed 's/[^a-z0-9-]//g' | \
-        cut -c1-50
-}
-# Ensure docs directory exists
-ensure_docs_dir() {
-    local subdir="$1"
-    mkdir -p ".docs/$subdir"
-}
-# Get full output path for a document
-get_doc_path() {
-    local subdir="$1"
-    local filename="$2"
-    ensure_docs_dir "$subdir"
-    echo ".docs/$subdir/$filename"
-}
-# Create timestamped status log path
-get_status_path() {
-    local timestamp
-    timestamp=$(get_timestamp)
-    get_doc_path "status" "${timestamp}.md"
-}
-# Create review report path
-get_review_path() {
-    local type="$1"
-    local branch_slug
-    local timestamp
-    branch_slug=$(get_branch_slug)
-    timestamp=$(get_timestamp)
-    get_doc_path "reviews/$branch_slug" "${type}-report.${timestamp}.md"
-}
-```
-### Usage Example
-```bash
-# Source helpers
-source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
-    # Inline fallback if script not found
-    get_timestamp() { date +%Y-%m-%d_%H%M; }
-    get_branch_slug() { git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone"; }
-    get_topic_slug() { echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50; }
-    ensure_docs_dir() { mkdir -p ".docs/$1"; }
-}
-# Use helpers
-TIMESTAMP=$(get_timestamp)
-BRANCH_SLUG=$(get_branch_slug)
-ensure_docs_dir "reviews/$BRANCH_SLUG"
-# Create output path
-OUTPUT=$(get_review_path "security")
-echo "Writing to: $OUTPUT"
-```
----
-## Templates
-### Status Log Template
-```markdown
-# Status Update - {TIMESTAMP}
-## Session Summary
-{Brief 2-3 sentence summary of what was accomplished}
-## Branch Context
-- **Branch**: {current_branch}
-- **Base**: {base_branch}
-- **Status**: {ahead/behind/clean}
-## Work Completed
-- {Task 1 completed}
-- {Task 2 completed}
-## Files Changed
-- `path/to/file1.ts` - {description}
-- `path/to/file2.ts` - {description}
-## Decisions Made
-- **{Decision}**: {Rationale}
-## Next Steps
-- [ ] {Next task 1}
-- [ ] {Next task 2}
-## Notes
-{Any additional context for future sessions}
-```
-### Debug Session Template
-```markdown
-# Debug Session - {DEBUG_SESSION_ID}
-## Problem Statement
-**Issue**: {description}
-**Reported**: {timestamp}
-**Branch**: {branch}
-## Expected vs Actual
-**Expected**: {what should happen}
-**Actual**: {what's happening}
-## Hypotheses Tested
-### Hypothesis 1: {description}
-- **Test**: {how tested}
-- **Result**: {confirmed/refuted}
-- **Evidence**: {what was observed}
-## Root Cause
-**Location**: {file:line}
-**Issue**: {precise description}
-**Why It Happened**: {chain of events}
-## Solution Applied
-**Fix**: {description}
-**Files Changed**: {list}
-**Verification**: {how verified}
-## Prevention
-- {How to prevent in future}
-```
-### STATUS INDEX.md Template
-```markdown
-# Status Log Index
-| Date | Summary | Branch |
-|------|---------|--------|
-| [2025-01-05_1430](./2025-01-05_1430.md) | Implemented auth | feat/auth |
-| [2025-01-04_0900](./2025-01-04_0900.md) | Fixed login bug | fix/login |
-```
-### DEBUG KNOWLEDGE_BASE.md Template
-```markdown
-# Debug Knowledge Base
-Searchable record of debugging sessions and solutions.
----
-## Issue: {description}
-**Date**: {date}
-**Session**: {session_id}
-**Category**: {error/performance/test/build}
-**Root Cause**: {brief}
-**Solution**: {brief}
-**Keywords**: {searchable terms}
-[Full details](./debug-{session_id}.md)
----
-```
----
-## Edge Cases
-### Detached HEAD State
-Branch slug falls back to "standalone":
-```bash
-# In detached HEAD
-get_branch_slug  # Returns: standalone
-# Review path becomes:
-# .docs/reviews/standalone/security-report.2025-01-05_1430.md
-```
-### Special Characters in Topics
-All special characters stripped:
-```bash
-get_topic_slug "Bug: User can't login (v2.0)"
-# Returns: bug-user-cant-login-v20
-```
-### Long Topic Names
-Truncated at 50 characters:
-```bash
-get_topic_slug "This is a very long topic name that exceeds the maximum allowed length"
-# Returns: this-is-a-very-long-topic-name-that-exceeds-the-m
-```
----
-## Quick Reference
-For violation examples and detection patterns, see [violations.md](violations.md).

package/shared/skills/docs-framework/references/violations.md DELETED Viewed

@@ -1,221 +0,0 @@
-# Documentation Framework Violations
-Common violations of documentation conventions with detection patterns and fixes.
----
-## Naming Convention Violations
-| Violation | Bad Example | Correct Example | Fix |
-|-----------|-------------|-----------------|-----|
-| Wrong timestamp format | `2025-1-5` | `2025-01-05_1430` | Use `YYYY-MM-DD_HHMM` |
-| Missing time in timestamp | `2025-01-05` | `2025-01-05_1430` | Include `_HHMM` suffix |
-| Unsanitized branch slug | `feature/auth` | `feature-auth` | Replace `/` with `-` |
-| Wrong case for artifacts | `Status-2025-01-05.md` | `2025-01-05_1430.md` | Use lowercase except special indexes |
-| Wrong case for indexes | `index.md` | `INDEX.md` | UPPERCASE for special indexes |
-| Files outside .docs | `docs/status.md` | `.docs/status/2025-01-05_1430.md` | Use `.docs/` root |
-| Missing INDEX.md | Status files without index | Create `INDEX.md` | Every directory needs index |
-| Special chars in slug | `oauth-2.0-auth` | `oauth-20-auth` | Strip non-alphanumeric except `-` |
----
-## Directory Structure Violations
-### Wrong: Flat Structure
-```
-project/
-├── status-2025-01-05.md    # Wrong location
-├── review-auth.md          # Missing timestamp, wrong location
-└── catch_up.md             # Wrong case, wrong location
-```
-### Wrong: Non-standard Subdirectories
-```
-.docs/
-├── logs/                   # Should be status/
-├── reports/                # Should be reviews/{branch-slug}/
-└── notes.md                # Should be in appropriate subdir
-```
----
-## Timestamp Violations
-### Missing Leading Zeros
-```bash
-# WRONG
-date +%Y-%m-%d_%H%M  # Could produce: 2025-1-5_930
-# RIGHT
-date +%Y-%m-%d_%H%M  # Always produces: 2025-01-05_0930
-```
-Note: `date` command handles padding, but manual timestamps often miss it.
-### Wrong Separator
-```bash
-# WRONG
-2025-01-05-1430   # Dash instead of underscore
-2025/01/05_1430   # Slash in date
-2025.01.05_1430   # Dot in date
-# RIGHT
-2025-01-05_1430   # Underscore separating date from time
-```
----
-## Branch Slug Violations
-### Unhandled Slash
-```bash
-# WRONG - produces invalid filename
-BRANCH_SLUG=$(git branch --show-current)
-# Result: feature/auth -> invalid path
-# RIGHT - sanitizes slash
-BRANCH_SLUG=$(git branch --show-current | sed 's/\//-/g')
-# Result: feature/auth -> feature-auth
-```
-### Missing Fallback
-```bash
-# WRONG - fails in detached HEAD
-BRANCH_SLUG=$(git branch --show-current)
-# Result: empty string -> broken path
-# RIGHT - with fallback
-BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
-# Result: (detached HEAD) -> standalone
-```
----
-## Topic Slug Violations
-### Preserving Special Characters
-```bash
-# WRONG - special chars break filenames
-TOPIC="Bug: Can't login (v2.0)"
-SLUG="Bug:-Can't-login-(v2.0)"
-# RIGHT - stripped and normalized
-SLUG="bug-cant-login-v20"
-```
-### Not Truncating Long Names
-```bash
-# WRONG - excessively long filename
-TOPIC="This is a very long topic name that describes the entire feature..."
-SLUG="this-is-a-very-long-topic-name-that-describes-the-entire-feature"
-# RIGHT - truncated at 50 chars
-SLUG="this-is-a-very-long-topic-name-that-describes-the"
-```
----
-## File Type Violations
-### Wrong Case for Special Files
-```bash
-# WRONG
-catch_up.md      # Should be CATCH_UP.md
-index.md         # Should be INDEX.md
-knowledge_base.md # Should be KNOWLEDGE_BASE.md
-# RIGHT - UPPERCASE for special indexes
-CATCH_UP.md
-INDEX.md
-KNOWLEDGE_BASE.md
-```
-### Wrong Case for Artifacts
-```bash
-# WRONG
-Status-2025-01-05_1430.md
-Security-Report.md
-# RIGHT - lowercase for artifacts
-2025-01-05_1430.md
-security-report.2025-01-05_1430.md
-```
----
-## Template Usage Violations
-### Missing Required Sections
-```markdown
-# WRONG - missing key sections
-# Status Update
-Did some work today.
-```
-```markdown
-# RIGHT - all required sections
-# Status Update - 2025-01-05_1430
-## Session Summary
-Implemented user authentication feature.
-## Branch Context
-- **Branch**: feat/auth
-- **Base**: main
-- **Status**: 3 commits ahead
-## Work Completed
-- Added JWT validation middleware
-- Created login endpoint
-## Files Changed
-- `src/auth/jwt.ts` - JWT utilities
-- `src/routes/login.ts` - Login endpoint
-## Next Steps
-- [ ] Add refresh token support
-- [ ] Write integration tests
-```
----
-## Detection Patterns
-Use these patterns to find violations:
-```bash
-# Find files outside .docs/
-find . -name "*.md" -path "*/docs/*" ! -path "*/.docs/*"
-# Find wrong timestamp format (missing underscore)
-grep -r "^\d{4}-\d{2}-\d{2}[^_]" .docs/
-# Find lowercase special indexes
-ls .docs/**/index.md .docs/**/catch_up.md 2>/dev/null
-# Find uppercase artifacts (excluding special files)
-find .docs -name "*.md" | grep -v "INDEX\|CATCH_UP\|KNOWLEDGE_BASE" | xargs -I {} basename {} | grep "^[A-Z]"
-# Find unsanitized branch names in paths
-find .docs/reviews -type d -name "*/*" 2>/dev/null
-```
----
-## Quick Reference
-For correct patterns and templates, see [patterns.md](patterns.md).

package/shared/skills/documentation-patterns/SKILL.md DELETED Viewed

@@ -1,125 +0,0 @@
----
-name: documentation-patterns
-description: This skill should be used when reviewing for documentation drift, missing API docs, or stale comments.
-user-invocable: false
-allowed-tools: Read, Grep, Glob
----
-# Documentation Patterns
-Domain expertise for documentation quality and alignment. Use alongside `review-methodology` for complete documentation reviews.
-## Iron Law
-> **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
-| Issue | Problem | Fix |
-|-------|---------|-----|
-| Missing docstrings | Complex functions without explanation | Add JSDoc with params, returns, throws |
-| Outdated comments | Comments that contradict code | Update or remove |
-| "What" comments | `// Loop through users` | Explain "why" instead |
-| Magic algorithms | Complex logic without explanation | Document algorithm and rationale |
-**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;
-```
-### 2. API Documentation Issues
-| Issue | Problem | Fix |
-|-------|---------|-----|
-| Missing params | Callers don't know valid values | Document all params with types and constraints |
-| 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 |
-|-------|---------|-----|
-| Code-comment drift | Comment says 3 retries, code does 5 | Update comment or use constant |
-| 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
----
-## Severity Guidelines
-| Severity | Description | Examples |
-|----------|-------------|----------|
-| **CRITICAL** | Actively misleading | Comments contradict code; API docs with wrong types; README with broken steps; Changelog missing breaking changes |
-| **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