User Says	Flow
"new challenge", "start a streak", "track a goal"	Flow 1: New Challenge
"check in", "log progress", "update my streak"	Flow 2: Check-in
"list challenges", "show all challenges"	Flow 3: List
"switch to [name]", "change challenge"	Flow 4: Switch
"show stats", "my progress"	Flow 5: Statistics
"show insights", "cross-challenge"	Flow 6: Insights
"export calendar", "create reminders"	Flow 7: Calendar
"reset challenge", "start fresh"	Flow 8: Reset
"pause [name]", "put on hold"	Flow 9: Pause
"archive [name]", "shelve challenge"	Flow 10: Archive
"resume [name]", "reactivate"	Flow 11: Resume

Data Storage

All data in .streak/ folder:

.streak/
├── config.md                     # Global settings
├── active.md                     # Current challenge pointer
└── challenges/
    └── [challenge-id]/
        ├── challenge-config.md   # Metadata, goal, progress
        ├── challenge-log.md      # Progress log with summary
        ├── today.md              # Today's session context
        ├── backlog.md            # Ideas to try
        ├── preferences.md        # Type-adaptive setup
        ├── context.md            # Linked resources
        ├── insights.md           # Auto-generated insights
        └── sessions/
            └── session-XXX/
                └── notes.md      # Session notes

File templates: See references/file-templates.md

Challenge Types

Type	Best For	Key Questions
Learning	Courses, books, skills	"Any aha moments?", "Progress on milestones?"
Building	Projects, shipping	"What did you ship?", "Any blockers?"
Fitness	Workouts, health	"What exercises?", "How did body feel?"
Creative	Art, writing, music	"What did you create?", "Any inspiration?"
Habit	Routines, consistency	"Did you complete it?", "How did it feel?"
Custom	Anything else	User-defined questions

Type details: See references/types.md

Flow 1: New Challenge

Initialize .streak/ folder if needed
Ask type: Learning, Building, Fitness, Creative, Habit, or Custom
Basic info: Name, goal, cadence (daily/every N days/weekly)
Type-specific questions: See references/types.md
Create files: All templates pre-filled based on answers
Set active and confirm

Detailed steps: See references/flows-detailed.md

Flow 2: Check-in

Two modes: Pre-session (planning) and Post-session (wrap-up)

Pre-Session Mode

Load context: Read active challenge, config, today.md, preferences, backlog
Show status: Session #, streak, days since last, on-track/due/overdue
Quick context: Energy/time, specific focus or "surprise me", constraints
Optional research: For Building/Learning types
Ideation: Type-adaptive suggestions based on energy and backlog
Prepare session: Create session folder and notes template

Post-Session Mode (user says "done")

Wrap-up questions: What worked on, how it went, what's next, key learning
Type-specific questions: See references/types.md
Save: Update session notes, challenge-config, challenge-log, backlog
Generate insights: Patterns, streaks, cross-challenge connections
Check achievements: See references/achievements.md
Completion message: Progress summary, achievements earned, insights

Shortcuts during flow:

Say	Action
"Just research"	Only research step
"Skip to suggestions"	Skip research
"I know what I'm doing: [idea]"	Skip ideation
"Done" / "Finished" / "Back"	Jump to wrap-up
"Quick check-in"	Minimal logging

Detailed steps: See references/flows-detailed.md

Flow 3: List Challenges

Display challenges grouped by status, sorted by priority then recency.

Default: Show active + paused challenges With --all flag: Include archived challenges

Sorting order (within each group):

Priority (higher number first, default 0)
Last check-in (most recent first)

Display format:

## Active Challenges
| | Name | Type | Pri | Streak | Last Check-in | Sessions |
|---|------|------|-----|--------|---------------|----------|
| * | python-courses | Learning | 10 | 5 days | 1 day ago | 3 |
|   | home-fitness | Fitness | 5 | 2 days | 2 days ago | 8 |

## Paused Challenges
|   | stories-to-novels | Writing | 0 | - | 10 days ago | 5 |

(2 archived challenges hidden - use --all to show)

* = Active challenge
Pri = Priority (edit in challenge-config.md)

With --all flag, also show:

## Archived Challenges
|   | old-project | Building | 0 | - | 2 months ago | 20 |

Flow 4: Switch Challenge

Validate challenge exists
Update active.md
Load new challenge context
Confirm with status

Flow 5: Statistics

Show for active challenge:

Progress: Sessions, days since start, completion rate
Streaks: Current, longest, average gap
Patterns: Best day, best time, average length
Achievements: Earned badges with dates
Backlog: Completed, in-progress, pending items

Flow 6: Cross-Challenge Insights

Analyze ALL challenges to detect:

Compound Learning: Skills from one challenge enabling another
Skill Transfer: Same concepts across challenges
Cross-Domain: Correlations between different types
Patterns: Best days, productivity trends
Suggestions: Personalized recommendations

Insight formats: See references/achievements.md

Flow 7: Calendar Export

Generate .ics file with check-in reminders:

Frequency based on cadence
30-day look-ahead (configurable)
Works with Google, Apple, Outlook calendars

Template: See references/file-templates.md

Flow 8: Reset Challenge

Archives current progress and starts fresh:

Archives log as challenge-log-archived-[date].md
Archives sessions folder
Resets streak counters
Keeps preferences, context, backlog intact

Flow 9: Pause Challenge

Temporarily pause a challenge (plan to resume later):

Validate challenge exists and is active
Update challenge-config.md: set **Status:** paused
If pausing the active challenge:
- List other active challenges
- Prompt: "Paused [name]. Switch to another challenge?"
- If yes, run Flow 4 (Switch)
Confirm: "Challenge [name] paused. Use /streak-resume [name] to reactivate."

Use cases: Seasonal challenges, focusing on other priorities, taking a break

Flow 10: Archive Challenge

Move challenge to long-term storage (out of daily view):

Validate challenge exists and is not already archived
Update challenge-config.md: set **Status:** archived
If archiving the active challenge:
- List other active challenges
- Prompt: "Archived [name]. Switch to another challenge?"
- If yes, run Flow 4 (Switch)
Confirm: "Challenge [name] archived. Use /streak-list --all to see archived challenges."

Use cases: Completed goals, abandoned challenges, historical record

Flow 11: Resume Challenge

Bring a paused or archived challenge back to active:

Validate challenge exists and is paused or archived
Update challenge-config.md: set **Status:** active
Ask: "Make [name] your active challenge?"
- If yes, update active.md
Check days since last check-in:
- If 7+ days: Award :muscle: Comeback badge
Confirm: "Challenge [name] is now active. Ready to check in?"

Note: Resuming does NOT reset streak - it continues from where you left off.

Achievements

Streak Badges

Badge	Requirement
:fire: First Flame	3-day streak
:fire::fire: On Fire	7-day streak
:fire::fire::fire: Unstoppable	30-day streak
:gem: Diamond Streak	100-day streak

Milestone Badges

Badge	Requirement
:footprints: First Step	First check-in
:star: Dedicated	10 sessions
:100: Centurion	100 sessions

Special Badges

Badge	Requirement
:link: Connected	First cross-challenge insight
:muscle: Comeback	Resume after 7+ days
:mortar_board: Graduate	Complete challenge goal

Full list: See references/achievements.md

Error Handling

Situation	Response
No `.streak/` folder	"No challenges found. Say: Start a new challenge"
No active challenge	List available challenges, prompt to switch or create
Challenge not found	List available, suggest closest match

Best Practices

Be specific in goals - "Complete Rustlings" > "Learn Rust"
Start sustainable - Every 2-3 days is easier than daily
Use today.md - Set context before sessions
Maintain backlog - Ideas for low-energy days
Review insights - Check weekly to see patterns
Celebrate streaks - Achievements are real motivation
Reset guilt-free - Archiving is progress, not failure
Cross-pollinate - Run multiple challenges to find connections

Reference Files

For detailed content, see:

File	Contains
`references/file-templates.md`	All file templates and structures
`references/types.md`	Type-specific questions, preferences, ideation
`references/flows-detailed.md`	Step-by-step flow instructions
`references/achievements.md`	Achievement system, insight generation

Examples

30 Days of AI/ML (Building)

Type: Building
Goal: Ship one AI-powered micro-app per day
Cadence: Daily
Stack: Python, TypeScript, Claude Code

Learn Rust (Learning)

Type: Learning
Goal: Complete Rustlings and build a CLI tool
Cadence: Every 2 days
Resources: Rustlings, The Rust Book

Morning Workout (Fitness)

Type: Fitness
Goal: Build consistent strength training habit
Cadence: Daily (with rest days)
Equipment: Home gym - dumbbells, pull-up bar

Daily Sketching (Creative)

Type: Creative
Goal: Draw one sketch per day for 100 days
Cadence: Daily
Medium: Digital art (Procreate)

Morning Meditation (Habit)

Type: Habit
Goal: Meditate 10 minutes every morning
Cadence: Daily
Trigger: After coffee, before email

streak

Streak

Quick Start