devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/design-review/references/anti-patterns.md

@@ -0,0 +1,207 @@
+# Design Anti-Patterns: Before/After Plan Examples
+
+Concrete before/after plan snippets for each of the 6 anti-patterns. Use these to recognize and correct problems in implementation plans.
+
+---
+
+## 1. N+1 Queries
+
+### Before (Anti-Pattern)
+```
+Step 4: Display order history page
+- Fetch list of orders for user (query: SELECT * FROM orders WHERE user_id = ?)
+- For each order, fetch the product name (query: SELECT name FROM products WHERE id = ?)
+- For each order, fetch the customer's address (query: SELECT * FROM addresses WHERE id = ?)
+- Render order list with product names and addresses
+```
+Problems: 1 query for orders + N queries for products + N queries for addresses = 1 + 2N total queries.
+
+### After (Corrected)
+```
+Step 4: Display order history page
+- Fetch orders for user with JOIN to products and addresses:
+  SELECT o.*, p.name as product_name, a.* 
+  FROM orders o
+  JOIN products p ON p.id = o.product_id
+  JOIN addresses a ON a.id = o.address_id
+  WHERE o.user_id = ?
+  ORDER BY o.created_at DESC
+  LIMIT 50
+- Render order list from joined result (1 query total)
+```
+
+---
+
+## 2. God Functions
+
+### Before (Anti-Pattern)
+```
+Step 3: Implement processCheckout() function
+- Validate cart items (stock available, prices match)
+- Apply discount codes
+- Calculate tax based on shipping address
+- Charge payment method via Stripe API
+- Create order record in database
+- Update inventory counts for each item
+- Send confirmation email to customer
+- Send fulfillment webhook to warehouse
+- Log analytics event
+- Return order confirmation
+```
+Problems: 9 responsibilities in 1 function. Untestable in isolation. Any change breaks everything.
+
+### After (Corrected)
+```
+Step 3: Implement checkout pipeline
+- validateCart(cart): verify stock and prices → Result<ValidatedCart, CartError>
+- applyDiscounts(cart, codes): → Result<PricedCart, DiscountError>
+- calculateTax(cart, address): → Result<TaxedCart, TaxError>
+- chargePayment(cart, paymentMethod): Stripe API call → Result<ChargedCart, PaymentError>
+- createOrder(chargedCart): DB write → Result<Order, DBError>
+- orchestrateCheckout(): calls above in sequence, rolls back on failure
+
+Post-order async (background jobs):
+- updateInventory(order): decrement stock counts
+- sendConfirmationEmail(order): customer notification
+- notifyWarehouse(order): fulfillment webhook
+- trackAnalytics(order): analytics event
+```
+
+---
+
+## 3. Missing Parallelism
+
+### Before (Anti-Pattern)
+```
+Step 5: Build user dashboard
+- Fetch user profile from DB
+- Then fetch recent orders from DB
+- Then fetch unread notification count from DB
+- Then fetch account balance from billing service
+- Then render dashboard with all data
+```
+Problems: 4 independent operations run sequentially. Total time = T1 + T2 + T3 + T4 instead of max(T1..T4).
+
+### After (Corrected)
+```
+Step 5: Build user dashboard
+- Fetch all data in parallel (no ordering dependency):
+  Promise.all([
+    fetchUserProfile(userId),         // ~10ms
+    fetchRecentOrders(userId, 10),     // ~20ms
+    fetchNotificationCount(userId),   // ~5ms
+    fetchAccountBalance(userId),      // ~30ms (billing service)
+  ])
+- Wait for all 4 to complete (total ~30ms, not ~65ms)
+- Render dashboard with combined result
+- Error handling: if any fetch fails, show partial data with error indicator for failed section
+```
+
+---
+
+## 4. Error Handling Gaps
+
+### Before (Anti-Pattern)
+```
+Step 7: Implement file upload
+- Receive multipart file upload from user
+- Validate file type and size
+- Upload to S3 bucket
+- Save file metadata to database
+- Return file URL to client
+```
+Problems: No failure paths. What if S3 is down? What if DB write fails after S3 upload? Orphaned files, data inconsistency.
+
+### After (Corrected)
+```
+Step 7: Implement file upload
+- Receive multipart file upload from user
+- Validate file type (JPEG/PNG/PDF only) and size (max 10MB)
+  - On validation failure: return 422 with specific error message, no upload attempted
+- Upload to S3 bucket
+  - On S3 timeout (>30s): return 503, log error, do not write to DB
+  - On S3 error: return 502 with "Storage unavailable", log error with request ID
+- Save file metadata to database
+  - On DB failure after successful S3 upload: 
+    - Queue cleanup job to delete orphaned S3 object
+    - Return 500, log error with S3 key for manual cleanup if queue fails
+- Return 201 with file URL and metadata
+- Idempotency: if file with same hash already exists for user, return existing URL (no duplicate upload)
+```
+
+---
+
+## 5. Missing Caching
+
+### Before (Anti-Pattern)
+```
+Step 2: Load application configuration
+- On each API request, fetch feature flags from feature-flag service
+- On each request, fetch user's role permissions from database
+- On each request, fetch supported currencies list from config service
+- Process request with loaded configuration
+```
+Problems: 3 external calls per request. At 1000 req/s = 3000 calls/s to config services. Latency added to every request.
+
+### After (Corrected)
+```
+Step 2: Load application configuration (cached)
+- Feature flags: cached in Redis, TTL 60s, refreshed on change event
+  - On cache miss: fetch from feature-flag service, write to Redis
+  - Stale-while-revalidate: serve stale if refresh fails (max 300s stale)
+- User permissions: cached per user in Redis, TTL 300s, invalidated on role change
+  - Cache key: `permissions:{userId}`
+  - On role change event: `DEL permissions:{userId}`
+- Supported currencies: in-process cache (singleton), TTL 1h, loaded at startup
+  - Currencies are static — process-level cache is sufficient
+  - Reload on explicit admin action only
+- Total added latency: ~0ms for cache hits (>99% of requests)
+```
+
+---
+
+## 6. Poor Decomposition
+
+### Before (Anti-Pattern)
+```
+Step 4: Handle user registration endpoint
+- Parse request body
+- Check if user is authenticated (if so, return 400)
+- Validate email format and uniqueness
+- Hash password with bcrypt
+- Create user record
+- Also send welcome email
+- Also create default workspace for user
+- Also log registration event for analytics
+- Also update user count metric
+- Return 201 with user object
+```
+Problems: HTTP handler contains business logic, side effects, and infrastructure concerns. Untestable without full stack.
+
+### After (Corrected)
+```
+Step 4: Handle user registration
+
+HTTP Layer (controller):
+- Parse and validate request body (email, password format, required fields)
+- Return 422 on validation failure with field-level errors
+- Call UserService.register(email, password)
+- Return 201 with user DTO on success; map domain errors to HTTP codes
+
+Domain Layer (UserService.register):
+- Check uniqueness (throws DuplicateEmailError if taken)
+- Hash password (bcrypt, cost 12)
+- Create User entity
+- Persist via UserRepository
+- Emit UserRegistered domain event
+- Return created User
+
+Event Handlers (async, triggered by UserRegistered event):
+- WelcomeEmailHandler: send welcome email
+- WorkspaceSetupHandler: create default workspace
+- AnalyticsHandler: log registration event
+- MetricsHandler: increment user count
+
+Separation: Controller handles HTTP. Service handles business logic. Events handle side effects.
+Each layer independently testable.
+```

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

@@ -0,0 +1,190 @@
+---
+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 .devflow/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 `.devflow/docs/` in the project root:
+
+```
+.devflow/docs/
+├── reviews/{branch-slug}/              # Code review reports per branch
+│   ├── .last-review-head              # HEAD SHA of last completed review (for incremental)
+│   ├── {timestamp}/                   # Timestamped review directory (YYYY-MM-DD_HHMM)
+│   │   ├── {focus}.md                 # Review agent report (e.g., security.md, architecture.md)
+│   │   ├── review-summary.md          # Synthesize agent output
+│   │   └── resolution-summary.md      # Written by /resolve (if run)
+│   └── {timestamp}/                   # Second review (incremental)
+│       ├── {focus}.md
+│       └── review-summary.md
+├── bug-analysis/{branch-slug}/          # Bug analysis reports per branch
+│   ├── .last-analysis-head            # HEAD SHA of last analysis (for incremental)
+│   └── {timestamp}/                   # Timestamped analysis directory (YYYY-MM-DD_HHMM)
+│       ├── {focus}.md                 # Analyzer report (e.g., security.md, functional.md)
+│       ├── static-findings.md         # Raw static analysis tool output
+│       ├── bug-analysis-summary.md    # Synthesize agent output
+│       └── resolution-summary.md      # Written by /resolve (if run)
+├── design/                             # Design artifacts from /plan
+│   └── {issue}-{topic-slug}.{timestamp}.md  # Design document
+├── tickets/{slug}/                     # Ticket sets from /dynamic-tickets
+│   └── {YYYY-MM-DD_HHMM}/             # Timestamped ticket directory
+│       ├── {ticket-slug}.md            # Individual ticket files
+│       └── tracking-issue.md           # Tracking issue body (GitHub sync)
+├── waves/{slug}/                       # Wave run reports from /dynamic-build
+│   └── {YYYY-MM-DD_HHMM}/             # Timestamped wave directory
+│       └── wave-report.md              # Wave run summary and status
+├── research/{topic-slug}/              # Research artifacts per topic
+│   └── {YYYY-MM-DD_HHMM}/             # Timestamped research directory
+│       ├── {type}.md                  # Research agent outputs (codebase.md, external.md, etc.)
+│       └── research-summary.md        # Synthesize agent output
+├── status/                             # Development logs
+│   ├── {timestamp}.md
+│   ├── compact/{timestamp}.md
+│   └── INDEX.md
+└── swarm/                              # Swarm operation state
+    ├── state.json
+    └── plans/
+
+.devflow/memory/
+├── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
+└── backup.json                         # Pre-compact git state snapshot
+
+.devflow/learning/
+├── decisions.md                        # Architectural decisions (ADR-NNN format)
+└── pitfalls.md                         # Known pitfalls (PF-NNN format)
+```
+
+---
+
+## 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` |
+| Review reports | `{focus}.md` in timestamped dir | `2025-12-26_1430/security.md` |
+| Review summary | `review-summary.md` in timestamped dir | `2025-12-26_1430/review-summary.md` |
+| Resolution summary | `resolution-summary.md` in timestamped dir | `2025-12-26_1430/resolution-summary.md` |
+| Review head marker | `.last-review-head` | Plain text file with SHA |
+| Status logs | `{timestamp}.md` | `2025-12-26_1430.md` |
+| Design documents | `{issue}-{topic-slug}.{timestamp}.md` | `42-jwt-auth.2026-04-07_1430.md` |
+| Research outputs | `{type}.md` in timestamped dir | `2025-12-26_1430/codebase.md` |
+| Research summary | `research-summary.md` in timestamped dir | `2025-12-26_1430/research-summary.md` |
+| Bug analysis reports | `{focus}.md` in timestamped dir | `2025-12-26_1430/security.md` |
+| Bug analysis summary | `bug-analysis-summary.md` in timestamped dir | `2025-12-26_1430/bug-analysis-summary.md` |
+| Static findings | `static-findings.md` in timestamped dir | `2025-12-26_1430/static-findings.md` |
+| Analysis head marker | `.last-analysis-head` | Plain text file with SHA |
+
+---
+
+## 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 ".devflow/docs/$1"; }
+}
+```
+
+---
+
+## Agent Persistence Rules
+
+### Agents That Persist Artifacts
+
+| Agent | Output Location | Behavior |
+|-------|-----------------|----------|
+| Review agent | `.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md` | Creates new in timestamped dir |
+| Synthesize agent (review) | `.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md` | Creates new in timestamped dir |
+| Resolve cmd | `.devflow/docs/reviews/{branch-slug}/{timestamp}/resolution-summary.md` | Written by /resolve orchestrator (Phase 5) |
+| Code-review cmd | `.devflow/docs/reviews/{branch-slug}/.last-review-head` | Overwrites with HEAD SHA |
+| Working Memory | `.devflow/memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
+| Decisions | `.devflow/learning/decisions.md` | Rendered from `decisions-ledger.jsonl` (active ADR-NNN rows; retired rows dropped) |
+| Pitfalls | `.devflow/learning/pitfalls.md` | Rendered from `decisions-ledger.jsonl` (active PF-NNN rows; retired rows dropped) |
+| Design agent (via /plan) | `.devflow/docs/design/{issue}-{topic-slug}.{timestamp}.md` | Creates new design artifact |
+| Research agent | `.devflow/docs/research/{topic-slug}/{timestamp}/{type}.md` | Creates new in timestamped dir |
+| Synthesize agent (research) | `.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md` | Creates new in timestamped dir |
+| Diagnose agent | `.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/{focus}.md` | Creates new in timestamped dir |
+| Synthesize agent (bug-analysis) | `.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/bug-analysis-summary.md` | Creates new in timestamped dir |
+| Bug-analysis cmd | `.devflow/docs/bug-analysis/{branch-slug}/.last-analysis-head` | Overwrites with HEAD SHA |
+
+### Agents That Don't Persist
+
+- Git (fetch-issue: read-only, post-review-summary: consolidated review comment only)
+- Code agent (commits to git, no .devflow/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 .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:
+- **Review agents**: Creates review reports
+- **Bug analysis agents**: Creates bug analysis reports
+- **Working Memory hooks**: Auto-maintains `.devflow/memory/WORKING-MEMORY.md`
+- **Learning agent**: background LLM agent (spawned via the session-start directive) promotes observations to ADRs/PFs via `assign-anchor`, which renders `decisions.md` / `pitfalls.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