devflow-kit 0.8.1 → 1.0.0

package/shared/skills/dependencies-patterns/references/violations.md

@@ -0,0 +1,247 @@
+# Extended Violation Examples
+
+Detailed examples of dependency violations by category.
+
+---
+
+## Security Vulnerability Violations
+
+### Known CVEs - Extended Examples
+
+```bash
+# Check for known vulnerabilities
+npm audit
+# or
+yarn audit
+# or
+pnpm audit
+
+# Output example:
+# High: Prototype Pollution in lodash
+# Package: lodash
+# Dependency of: my-package
+# Path: my-package > lodash
+# More info: https://github.com/advisories/GHSA-xxx
+```
+
+### Vulnerable Version Ranges
+
+```json
+// PROBLEM: Wide version range includes vulnerable versions
+{
+  "dependencies": {
+    "lodash": "^4.0.0"  // Includes vulnerable 4.17.0-4.17.20
+  }
+}
+
+// SOLUTION: Pin to safe version or use range excluding vulnerable
+{
+  "dependencies": {
+    "lodash": "^4.17.21"  // First safe version
+  }
+}
+```
+
+### Malicious Package Red Flags
+
+```json
+// RED FLAGS for potentially malicious packages:
+{
+  "dependencies": {
+    "loadsh": "1.0.0",           // Typosquat of "lodash"
+    "event-stream": "3.3.6",     // Known compromised version
+    "random-unknown-pkg": "0.0.1" // No downloads, no repo
+  }
+}
+
+// VERIFY packages:
+// - Check npm page for download counts
+// - Verify repository link
+// - Check maintainer history
+// - Look for typosquatting
+```
+
+---
+
+## Version Management Violations
+
+### Unpinned Versions
+
+```json
+// PROBLEM: Can get different versions on each install
+{
+  "dependencies": {
+    "express": "*",           // Any version!
+    "lodash": "latest",       // Whatever is latest
+    "moment": ""              // Empty = latest
+  }
+}
+
+// SOLUTION: Pin exact or use caret with lockfile
+{
+  "dependencies": {
+    "express": "4.18.2",      // Exact pin
+    "lodash": "^4.17.21",     // Caret + lockfile
+    "moment": "~2.29.4"       // Tilde for patch only
+  }
+}
+```
+
+### Missing Lockfile
+
+```bash
+# PROBLEM: No lockfile committed
+.gitignore:
+package-lock.json  # Don't ignore this!
+yarn.lock          # Don't ignore this!
+
+# SOLUTION: Commit lockfile
+git add package-lock.json  # or yarn.lock
+git commit -m "Add lockfile for reproducible builds"
+```
+
+### Dependency Conflicts
+
+```bash
+# PROBLEM: Multiple versions of same package
+npm ls react
+# my-app
+# +-- react@18.2.0
+# \-- some-library
+#     \-- react@17.0.2  # Conflict!
+
+# SOLUTION: Use resolutions/overrides
+# package.json (yarn)
+{
+  "resolutions": {
+    "react": "18.2.0"
+  }
+}
+
+# package.json (npm)
+{
+  "overrides": {
+    "react": "18.2.0"
+  }
+}
+```
+
+---
+
+## Dependency Health Violations
+
+### Outdated Packages
+
+```bash
+# Check for outdated
+npm outdated
+
+# Package          Current  Wanted  Latest
+# lodash           4.17.15  4.17.21 4.17.21  # Security update!
+# typescript       4.9.5    4.9.5   5.3.2    # Major version
+# @types/node      18.0.0   18.19.0 20.10.0  # Minor updates
+
+# Prioritize:
+# 1. Security patches (lodash)
+# 2. Bug fixes (minor updates)
+# 3. Major versions (careful review)
+```
+
+### Unused Dependencies
+
+```bash
+# Find unused dependencies
+npx depcheck
+
+# Unused dependencies:
+# * moment           # Listed but never imported
+# * lodash           # Listed but never imported
+
+# SOLUTION: Remove unused
+npm uninstall moment lodash
+```
+
+### Unnecessary Heavy Dependencies
+
+```json
+// PROBLEM: Heavy dependencies for simple tasks
+{
+  "dependencies": {
+    "moment": "^2.29.4",     // 300KB for date formatting
+    "lodash": "^4.17.21",    // 70KB for one function
+    "left-pad": "^1.3.0"     // 1KB for string padding
+  }
+}
+
+// SOLUTION: Use native or lighter alternatives
+// Native date formatting
+new Date().toLocaleDateString();
+
+// Native array methods instead of lodash
+array.filter(x => x.active);
+
+// Native string padding
+'5'.padStart(2, '0');
+
+// Or import only what you need
+import { debounce } from 'lodash/debounce';
+```
+
+---
+
+## License Violations
+
+### Incompatible Licenses
+
+```bash
+# Check licenses
+npx license-checker --summary
+
+# Watch for incompatible combinations:
+# - GPL in MIT project (viral license)
+# - Commercial-only licenses
+# - AGPL in SaaS (requires source disclosure)
+
+# Example problematic output:
+# GPL-3.0: some-package  # Requires your code to be GPL too!
+```
+
+### Missing License
+
+```bash
+# Find packages without license
+npx license-checker --onlyunknown
+
+# Packages with unknown license:
+# - internal-company-pkg@1.0.0  # Verify this is intentional
+```
+
+---
+
+## Supply Chain Violations
+
+### Transitive Dependencies
+
+```bash
+# Check dependency tree depth
+npm ls --all | wc -l
+# If > 1000, high supply chain risk
+
+# Audit transitive deps
+npm audit --all
+
+# SOLUTION: Minimize dependencies, audit regularly
+```
+
+### Maintainer Concerns
+
+```json
+// RED FLAGS:
+// - Package with 1 maintainer who's inactive
+// - No recent releases but many open issues
+// - Repository archived or deleted
+// - Maintainer account compromised (check news)
+
+// Check package health:
+// https://snyk.io/advisor/npm-package/{package-name}
+```

package/shared/skills/docs-framework/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: docs-framework
+description: This skill should be used when the user asks to "create a review report", "write a status log", "add documentation", "name this artifact", or creates files in the .docs/ directory. Provides naming conventions, templates, and directory structure for reviews, debug sessions, design docs, and all persistent DevFlow documentation artifacts.
+user-invocable: false
+allowed-tools: Read, Bash, Glob
+---
+
+# Documentation Framework
+
+The canonical source for documentation conventions in DevFlow. All agents that persist artifacts must follow these standards.
+
+## Iron Law
+
+> **ALL ARTIFACTS FOLLOW NAMING CONVENTIONS**
+>
+> Timestamps are `YYYY-MM-DD_HHMM`. Branch slugs replace `/` with `-`. Topic slugs are
+> lowercase alphanumeric with dashes. No exceptions. Inconsistent naming breaks tooling,
+> searching, and automation. Follow the pattern or fix the pattern for everyone.
+
+---
+
+## Directory Structure
+
+All generated documentation lives under `.docs/` in the project root:
+
+```
+.docs/
+├── reviews/{branch-slug}/              # Code review reports per branch
+│   ├── {type}-report.{timestamp}.md
+│   └── review-summary.{timestamp}.md
+├── status/                             # Development logs
+│   ├── {timestamp}.md
+│   ├── compact/{timestamp}.md
+│   └── INDEX.md
+├── swarm/                              # Swarm operation state
+│   ├── state.json
+│   └── plans/
+└── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
+```
+
+---
+
+## Naming Conventions
+
+### Timestamps
+Format: `YYYY-MM-DD_HHMM` (sortable, readable)
+```bash
+TIMESTAMP=$(date +%Y-%m-%d_%H%M)  # Example: 2025-12-26_1430
+```
+
+### Branch Slugs
+Replace `/` with `-`, sanitize special characters:
+```bash
+BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "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)
+```
+
+### File Naming Patterns
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Special indexes | `UPPERCASE.md` | `WORKING-MEMORY.md`, `INDEX.md` |
+| Reports | `{type}-report.{timestamp}.md` | `security-report.2025-12-26_1430.md` |
+| Status logs | `{timestamp}.md` | `2025-12-26_1430.md` |
+
+---
+
+## Helper Functions
+
+Source helpers for consistent naming:
+
+```bash
+source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
+    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"; }
+}
+```
+
+---
+
+## Agent Persistence Rules
+
+### Agents That Persist Artifacts
+
+| Agent | Output Location | Behavior |
+|-------|-----------------|----------|
+| Reviewer | `.docs/reviews/{branch-slug}/{type}-report.{timestamp}.md` | Creates new |
+| Working Memory | `.docs/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
+
+### Agents That Don't Persist
+
+- Git (fetch-issue: read-only, comment-pr: PR comments only)
+- Coder (commits to git, no .docs/ output)
+
+---
+
+## Implementation Checklist
+
+When creating or modifying persisting agents:
+
+- [ ] Use standard timestamp format (`YYYY-MM-DD_HHMM`)
+- [ ] Sanitize branch names (replace `/` with `-`)
+- [ ] Sanitize topic names (lowercase, dashes, alphanumeric)
+- [ ] Create directory with `mkdir -p .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:
+- **Review agents**: Creates review reports
+- **Working Memory hooks**: Auto-maintains `.docs/WORKING-MEMORY.md`
+
+All persisting agents should load this skill to ensure consistent documentation.
+
+---
+
+## 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/shared/skills/docs-framework/references/patterns.md

@@ -0,0 +1,346 @@
+# 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).