@pjmendonca/devflow 1.13.2 → 1.19.0

package/tooling/completions/run-story-completion.bash

@@ -23,10 +23,10 @@ _run_story_completion() {
     COMPREPLY=()
     cur="${COMP_WORDS[COMP_CWORD]}"
     prev="${COMP_WORDS[COMP_CWORD-1]}"
-    
+
     # Main options
     opts="--swarm --pair --auto-route --sequential --agents --max-iterations --model --budget --memory --query --route-only --quiet --debug --dry-run --help"
-    
+
     case "${prev}" in
         --agents|-a)
             # Support comma-separated agent completion
@@ -38,7 +38,7 @@ _run_story_completion() {
                 existing_agents=""
                 current_part="$cur"
             fi
-            
+
             local suggestions=""
             for agent in $_devflow_agents; do
                 if [[ "$agent" == ${current_part}* ]]; then
@@ -67,7 +67,7 @@ _run_story_completion() {
         *)
             ;;
     esac
-    
+
     # Complete options
     if [[ ${cur} == -* ]]; then
         COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -81,9 +81,9 @@ _run_collab_completion() {
     COMPREPLY=()
     cur="${COMP_WORDS[COMP_CWORD]}"
     prev="${COMP_WORDS[COMP_CWORD-1]}"
-    
+
     opts="--swarm --pair --auto --sequential --agents --max-iterations --model --budget --memory --query --route-only --quiet --help"
-    
+
     case "${prev}" in
         --agents)
             local existing_agents current_part
@@ -94,7 +94,7 @@ _run_collab_completion() {
                 existing_agents=""
                 current_part="$cur"
             fi
-            
+
             local suggestions=""
             for agent in $_devflow_agents; do
                 if [[ "$agent" == ${current_part}* ]]; then
@@ -119,7 +119,7 @@ _run_collab_completion() {
         *)
             ;;
     esac
-    
+
     if [[ ${cur} == -* ]]; then
         COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
         return 0

package/tooling/docs/DOC-STANDARD.md

@@ -1,14 +1,14 @@
-# Documentation Standard - Stronger Project
+# Documentation Standard - Devflow
 
-**Version**: 1.0
-**Last Updated**: 2025-12-20
+**Version**: 1.1
+**Last Updated**: 2025-12-27
 **Applies To**: All documentation in `tooling/docs/`
 
 ---
 
 ## Purpose
 
-This document defines the standard format, structure, and conventions for all documentation in the Stronger project's `tooling/docs/` directory.
+This document defines the standard format, structure, and conventions for all documentation in the Devflow project's `tooling/docs/` directory.
 
 ---
 
@@ -212,26 +212,26 @@ Always include header separator:
 
 ### Alerts/Callouts
 
-Use these emoji conventions:
+Use these text-based conventions (no emojis per project policy):
 
 ```markdown
-  **WARNING**: Important warning
+**[WARNING]**: Important warning
 
- **TIP**: Helpful tip
+**[TIP]**: Helpful tip
 
- **NOTE**: Additional information
+**[NOTE]**: Additional information
 
- **CRITICAL**: Critical information
+**[CRITICAL]**: Critical information
 
- **SUCCESS**: Successful outcome
+**[OK]**: Successful outcome
 
- **ERROR**: Error or failure
+**[ERROR]**: Error or failure
 
-**GOAL**: Objective or target
+**[GOAL]**: Objective or target
 
- **DATA**: Data or statistics
+**[INFO]**: Data or statistics
 
- **TECHNICAL**: Technical details
+**[TECHNICAL]**: Technical details
 ```
 
 ---

package/tooling/docs/templates/brainstorm-guide.md

@@ -0,0 +1,314 @@
+# Brainstorming Techniques Guide
+
+This guide provides structured approaches for product discovery and story creation during Devflow initialization and brainstorming sessions.
+
+---
+
+## Technique 1: Guided Discovery (Socratic Method)
+
+Progressive questioning to uncover product vision and features.
+
+### Vision Questions
+
+1. **Problem Space**
+   - What problem are you solving?
+   - Who experiences this problem most acutely?
+   - What happens if this problem isn't solved?
+
+2. **Target Users**
+   - Who is your primary user?
+   - What's their current workflow/workaround?
+   - What frustrates them most about existing solutions?
+
+3. **Success Definition**
+   - What does success look like in 6 months?
+   - How will you measure success?
+   - What's the one thing this product MUST do well?
+
+4. **Competitive Landscape**
+   - What alternatives exist today?
+   - What's your unfair advantage?
+   - Why would users switch to your solution?
+
+### Feature Discovery Questions
+
+1. **Core Value**
+   - What's the minimum feature set for first value delivery?
+   - If you could only ship one feature, what would it be?
+   - What features are table stakes vs. differentiators?
+
+2. **User Journey**
+   - What's the first thing a new user should do?
+   - What action leads to the "aha moment"?
+   - What would make users come back daily?
+
+3. **Constraints**
+   - What's technically hardest about this product?
+   - What regulatory or compliance constraints exist?
+   - What's your deadline or launch constraint?
+
+---
+
+## Technique 2: User Journey Mapping
+
+Walk through user flows to discover features systematically.
+
+### Journey Framework
+
+```
+TRIGGER -> ENTRY -> CORE ACTIONS -> SUCCESS -> RETENTION
+```
+
+### Journey Questions by Stage
+
+**1. Trigger (What brings users?)**
+- How do users discover your product?
+- What motivates them to try it?
+- What's their emotional state when starting?
+
+**2. Entry (First experience)**
+- What's the onboarding flow?
+- What information do you need from users?
+- How quickly can they see value?
+
+**3. Core Actions (Main usage)**
+- What are the 3-5 primary actions users take?
+- What workflows are most common?
+- What data do they create/consume?
+
+**4. Success (Value delivery)**
+- What outcome indicates success for the user?
+- How do they know they've achieved their goal?
+- What feedback loops exist?
+
+**5. Retention (Coming back)**
+- Why would users return?
+- What triggers re-engagement?
+- How does value compound over time?
+
+### Journey Mapping Exercise
+
+```
+For each user type, complete:
+
+User: [Name/Persona]
+Goal: [What they want to achieve]
+
+Journey:
+1. [Trigger] -> Feature: ___
+2. [Entry] -> Feature: ___
+3. [Action 1] -> Feature: ___
+4. [Action 2] -> Feature: ___
+5. [Action 3] -> Feature: ___
+6. [Success] -> Feature: ___
+7. [Return] -> Feature: ___
+```
+
+---
+
+## Technique 3: Rapid Feature List
+
+Fast ideation followed by grouping and prioritization.
+
+### Phase 1: Ideation (5 minutes)
+
+Rules:
+- No filtering - capture everything
+- Quantity over quality
+- Build on others' ideas
+- No criticism yet
+
+Prompt questions:
+- What features do competitors have?
+- What would make users say "wow"?
+- What automation would save time?
+- What information do users need?
+- What actions should be one-click?
+
+### Phase 2: Grouping (3 minutes)
+
+Group features into:
+- **User Management** (auth, profiles, settings)
+- **Core Features** (primary value proposition)
+- **Data & Content** (creation, display, storage)
+- **Social/Sharing** (collaboration, communication)
+- **Analytics/Insights** (reporting, tracking)
+- **Integrations** (third-party connections)
+- **Admin/Settings** (configuration, management)
+
+### Phase 3: Prioritization (5 minutes)
+
+Use MoSCoW method:
+- **Must Have**: Critical for launch, non-negotiable
+- **Should Have**: Important but can work around
+- **Could Have**: Nice to have, enhances experience
+- **Won't Have**: Out of scope for now
+
+### Rapid List Template
+
+```
+MUST HAVE (MVP)
+- [ ] Feature 1
+- [ ] Feature 2
+- [ ] Feature 3
+
+SHOULD HAVE (v1.1)
+- [ ] Feature 4
+- [ ] Feature 5
+
+COULD HAVE (Later)
+- [ ] Feature 6
+- [ ] Feature 7
+
+WON'T HAVE (Not now)
+- [ ] Feature 8
+```
+
+---
+
+## Technique 4: Story Decomposition
+
+Breaking epics into implementable stories.
+
+### INVEST Criteria
+
+Every story should be:
+- **I**ndependent: Can be built separately
+- **N**egotiable: Details can be discussed
+- **V**aluable: Delivers user value
+- **E**stimable: Can be sized
+- **S**mall: Fits in a sprint
+- **T**estable: Has clear acceptance criteria
+
+### Decomposition Strategies
+
+**1. By User Role**
+```
+Epic: User Authentication
+-> Story: User can sign up with email
+-> Story: Admin can invite users
+-> Story: User can reset password
+```
+
+**2. By Workflow Step**
+```
+Epic: Checkout Flow
+-> Story: User can add items to cart
+-> Story: User can enter shipping address
+-> Story: User can complete payment
+```
+
+**3. By Data Operation (CRUD)**
+```
+Epic: Task Management
+-> Story: User can create a task
+-> Story: User can view task list
+-> Story: User can edit a task
+-> Story: User can delete a task
+```
+
+**4. By Happy Path + Edge Cases**
+```
+Epic: File Upload
+-> Story: User can upload single file (happy path)
+-> Story: System handles invalid file types
+-> Story: System handles upload failures
+```
+
+### Story Sizing Reference
+
+| Size | Description | Example |
+|------|-------------|---------|
+| XS | < 2 hours | Add a button, fix typo |
+| S | 2-4 hours | Simple form, basic API endpoint |
+| M | 1-2 days | Feature with UI + API + tests |
+| L | 3-5 days | Complex feature, multiple components |
+| XL | 1+ week | Should be broken down further |
+
+---
+
+## Technique 5: Prioritization Frameworks
+
+### RICE Scoring
+
+```
+Score = (Reach x Impact x Confidence) / Effort
+
+Reach: Number of users affected per quarter
+Impact: 3=massive, 2=high, 1=medium, 0.5=low, 0.25=minimal
+Confidence: 100%, 80%, 50%
+Effort: Person-weeks
+```
+
+### Impact/Effort Matrix
+
+```
+        HIGH IMPACT
+             |
+   Quick     |    Big Bets
+   Wins      |    (schedule these)
+   (do first)|
+-------------+-------------
+   Fill-ins  |    Time Sinks
+   (maybe)   |    (avoid)
+             |
+        LOW IMPACT
+
+      LOW EFFORT  |  HIGH EFFORT
+```
+
+### Priority Labels
+
+| Priority | Meaning | Timing |
+|----------|---------|--------|
+| P0 | Critical | This sprint, drop everything |
+| P1 | High | Next sprint |
+| P2 | Medium | This quarter |
+| P3 | Low | Backlog |
+
+---
+
+## Quick Reference: Init Session (10 min)
+
+1. **Vision** (2 min)
+   - What problem are you solving?
+   - Who's your primary user?
+
+2. **Core Features** (3 min)
+   - What's the one thing this must do well?
+   - What are the 3-5 core features?
+
+3. **First Sprint** (3 min)
+   - What's your MVP scope?
+   - Pick 3-5 stories for sprint 1
+
+4. **Wrap-up** (2 min)
+   - Review and confirm
+   - Generate story files
+
+---
+
+## Full Workshop Reference (30 min)
+
+1. **Vision Discovery** (5 min)
+   - Complete vision questions
+   - Define success metrics
+
+2. **User Journey Mapping** (8 min)
+   - Map 1-2 primary user journeys
+   - Extract features from each step
+
+3. **Rapid Feature List** (7 min)
+   - Brainstorm all features
+   - Group by category
+   - Apply MoSCoW
+
+4. **Story Decomposition** (7 min)
+   - Break down Must Have features
+   - Apply INVEST criteria
+   - Size stories
+
+5. **Sprint Planning** (3 min)
+   - Select sprint 1 stories
+   - Verify capacity fit
+   - Generate files

package/tooling/docs/templates/migration-spec.md

@@ -96,7 +96,7 @@
 1. **[Change Description 1]**
    - Files affected: `path/to/file`
    - Changes needed: [describe the code changes]
-   
+
 2. **[Change Description 2]**
    - Files affected: `path/to/file`
    - Changes needed: [describe the code changes]
@@ -243,13 +243,13 @@ If automated rollback fails:
 *To be filled after migration*
 
 ### What Went Well
-- 
+-
 
 ### What Could Be Improved
-- 
+-
 
 ### Action Items
-- 
+-
 
 ## Notes
 

package/tooling/docs/templates/story.md

@@ -0,0 +1,66 @@
+# STORY-{sprint}-{number}-{slug}
+
+**Type**: Feature
+**Status**: backlog | drafted | ready-for-dev | in-progress | review | done
+**Sprint**: {sprint}
+**Priority**: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Effort**: XS | S | M | L | XL
+**Created**: {date}
+**Last Updated**: {date}
+
+---
+
+## Summary
+
+{One-line description of what this story delivers}
+
+## User Story
+
+As a **{user type}**,
+I want **{goal/desire}**,
+So that **{benefit/value}**.
+
+## Context
+
+{Why is this story important? What problem does it solve? Background information.}
+
+## Acceptance Criteria
+
+- [ ] **AC-1**: {Specific, testable criterion}
+- [ ] **AC-2**: {Specific, testable criterion}
+- [ ] **AC-3**: {Specific, testable criterion}
+
+## Technical Notes
+
+{Implementation hints, architectural considerations, API contracts, data structures}
+
+## Business Rules
+
+- {Rule 1}: {Business logic that must be enforced}
+- {Rule 2}: {Validation or constraint}
+
+## Dependencies
+
+- {Story or system this depends on}
+
+## Out of Scope
+
+- {What this story explicitly does NOT include}
+
+## UI/UX Notes
+
+{Wireframes, mockups, or design specifications if applicable}
+
+## Testing Strategy
+
+- **Unit Tests**: {What to test at unit level}
+- **Integration Tests**: {What to test at integration level}
+- **Manual QA**: {Scenarios requiring manual verification}
+
+## Definition of Done
+
+- [ ] Code implemented and compiles
+- [ ] All acceptance criteria met
+- [ ] Tests written and passing
+- [ ] Code reviewed
+- [ ] Documentation updated (if applicable)

package/tooling/scripts/context_checkpoint.py

@@ -25,12 +25,15 @@ from datetime import datetime
 from pathlib import Path
 from typing import Optional
 
+from lib.colors import Colors
+from lib.platform import IS_WINDOWS
+
 # Configuration
 PROJECT_ROOT = Path(__file__).parent.parent.parent
 CHECKPOINT_DIR = PROJECT_ROOT / "tooling" / ".automation" / "checkpoints"
 LOGS_DIR = PROJECT_ROOT / "tooling" / ".automation" / "logs"
 # Platform-specific CLI command
-CLAUDE_CLI = "claude.cmd" if sys.platform == "win32" else "claude"
+CLAUDE_CLI = "claude.cmd" if IS_WINDOWS else "claude"
 
 # Context thresholds
 CONTEXT_WARNING_THRESHOLD = 0.75  # 75% - Start warning
@@ -38,19 +41,6 @@ CONTEXT_CRITICAL_THRESHOLD = 0.85  # 85% - Auto-checkpoint
 CONTEXT_EMERGENCY_THRESHOLD = 0.95  # 95% - Force checkpoint
 
 
-# Colors for terminal output
-class Colors:
-    HEADER = "\033[95m"
-    BLUE = "\033[94m"
-    CYAN = "\033[96m"
-    GREEN = "\033[92m"
-    YELLOW = "\033[93m"
-    RED = "\033[91m"
-    BOLD = "\033[1m"
-    UNDERLINE = "\033[4m"
-    END = "\033[0m"
-
-
 class ContextCheckpointManager:
     """Manages context checkpointing for Claude Code sessions."""
 
@@ -69,7 +59,7 @@ class ContextCheckpointManager:
         # Handle graceful shutdown (Windows-compatible)
         signal.signal(signal.SIGINT, self._signal_handler)
         # SIGTERM is not available on Windows
-        if sys.platform != "win32":
+        if not IS_WINDOWS:
             signal.signal(signal.SIGTERM, self._signal_handler)
 
     def _signal_handler(self, signum, frame):