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
"setup notifications", "telegram reminders"	Flow 12: Notifications
"setup telegram bot", "deploy telegram", "streak-telegram"	Flow 13: Telegram Bot Deploy

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.

Flow 12: Notifications Setup

Set up push notifications for due/overdue check-ins via Telegram.

Step 1: Create Telegram Bot

Open Telegram and message @BotFather
Send /newbot and follow prompts
Copy the bot token (looks like 123456789:ABCdefGHI...)

Step 2: Get Chat ID

Message @userinfobot on Telegram
Copy your chat ID (a number like 123456789)

Step 3: Configure

Add to .streak/config.md:

## Notifications (Optional)

- **Notifications:** enabled
- **Telegram Bot Token:** 123456789:ABCdefGHI...
- **Telegram Chat ID:** 123456789

Step 4: Schedule Notifications

Option A: Cron (Linux/Mac)

# Run daily at 9am
0 9 * * * cd /path/to/project && python .streak/../tools/streak-notify.py

Option B: GitHub Actions

# .github/workflows/streak-notify.yml
name: Streak Reminder
on:
  schedule:
    - cron: '0 9 * * *'  # 9am UTC daily
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: python tools/streak-notify.py .streak

Step 5: Test

python tools/streak-notify.py /path/to/.streak

Detailed steps: See tools/streak-notify.py header comments.

Flow 13: Telegram Bot Deploy

One-command deployment of the interactive Telegram bot with Docker.

Prerequisites (User Must Complete First)

Create Telegram Bot: Message @BotFather → /newbot → save token
Get Chat ID: Message @userinfobot → save Id number
Message your bot: Send /start to your bot (required before it can message you)

Create .env file in your project root:

cat > .env << EOF
TELEGRAM_BOT_TOKEN=your-bot-token
ALLOWED_USERS=your-chat-id
EOF

Docker must be installed and running

Flow Steps

Verify prerequisites:
- Check .env file exists in project root
- Check TELEGRAM_BOT_TOKEN is set (not empty/placeholder)
- Check Docker is available (docker --version)
- If any missing, show specific instructions and stop

Locate skill tools directory:

# Plugin location (typical paths)
~/.claude-code/plugins/ccc-skills@ccc/streak/tools/
# Or within the ccc repo if running locally

Copy bot files to project root:

cp [tools-dir]/streak-bot.py ./streak-bot.py
cp [tools-dir]/Dockerfile ./Dockerfile
cp [tools-dir]/docker-compose.yml ./docker-compose.yml

Ensure .gitignore protects secrets:

# Add if not present
echo ".env" >> .gitignore

Start the bot:
```
docker-compose up -d --build
```

Verify bot is running:

docker-compose ps
docker-compose logs --tail=20

Confirm to user:

✅ Telegram bot deployed!

Bot is running in Docker and will auto-restart on reboot.

Commands:
- docker-compose logs -f    # View logs
- docker-compose restart    # Restart bot
- docker-compose down       # Stop bot

Open Telegram and send /start to your bot to test!

Error Handling

Issue	Response
No .env file	Show: "Create .env first with TELEGRAM_BOT_TOKEN and ALLOWED_USERS"
Empty token	Show: "TELEGRAM_BOT_TOKEN in .env is empty - add your bot token from @BotFather"
Docker not found	Show: "Docker not installed. Install from https://docker.com"
Docker not running	Show: "Docker daemon not running. Start Docker Desktop or run: sudo systemctl start docker"
Port conflict	Show: "Another service using the port. Stop other bots first: docker-compose down"

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

Design Philosophy

Your challenges are interconnected. Your fitness affects your work. Your learning enables your building. Your habits shape your creativity.

Streak detects cross-challenge connections - patterns you might miss:

"Morning workouts correlate with productive coding days"
"Skills from 'Learn Rust' enabled progress in 'Build CLI Tools'"

This is the unique value - not just tracking, but understanding how challenges interact.

One Place, All Challenges

Put ALL challenges in ONE .streak/ folder, regardless of life area:

.streak/challenges/
├── work-project      # Work
├── morning-fitness   # Health
├── learn-rust        # Learning
└── daily-meditation  # Habit

Use /streak-switch to navigate. Use /streak-insights to discover connections.

Don't create separate .streak/ folders for different challenges. That defeats the purpose.

Best Practices

Keep challenges together - One .streak/ folder for ALL challenges (work, health, learning, etc.)
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