devflow-kit 0.9.0 → 1.1.0

package/plugins/devflow-core-skills/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).

package/plugins/devflow-core-skills/skills/docs-framework/references/violations.md

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