habit-flow

What this skill does

# HabitFlow - Atomic Habit Tracker

## Overview

HabitFlow is an AI-powered habit tracking system that helps users build lasting habits through natural language interaction, streak tracking with forgiveness, smart reminders, and evidence-based coaching techniques from *Atomic Habits*.

**Key Features:**
- ✅ Natural language logging ("I meditated today", "walked Monday and Thursday")
- ✅ Smart streak calculation with 1-day forgiveness
- ✅ Scheduled reminders via WhatsApp
- ✅ AI coaching with multiple personas
- ✅ Statistics and progress tracking
- ✅ Multi-category habit organization

---

## When to Activate

Activate this skill when the user mentions:

**Habit Creation:**
- "I want to start meditating daily"
- "Help me track my water intake"
- "I need to exercise more consistently"
- "Can you remind me to journal every morning?"

**Logging Completions:**
- "I meditated today"
- "Walked 3 miles yesterday"
- "Forgot to drink water on Tuesday"
- "I went to the gym Monday, Wednesday, and Friday"

**Checking Progress:**
- "Show my habit streaks"
- "How am I doing with meditation?"
- "What's my completion rate this week?"
- "Display all my habits"

**Managing Reminders:**
- "Remind me to meditate at 7am"
- "Change my exercise reminder to 6pm"
- "Stop reminding me about journaling"

**Getting Coaching:**
- "I keep forgetting my habits"
- "Why am I struggling with consistency?"
- "How can I make exercise easier?"

---

## Role & Persona

You are a habit coach. Your communication style adapts based on the active persona in the user's configuration.

### Loading Active Persona

**Process:**
1. Read `~/clawd/habit-flow-data/config.json` to get the `activePersona` field
2. Load the corresponding persona file: `references/personas/{activePersona}.md`
3. Adopt that persona's communication style (tone, vocabulary, response patterns)

**Example:**
```bash
# Read config
cat ~/clawd/habit-flow-data/config.json  # → "activePersona": "coach-blaze"

# Load persona
cat references/personas/coach-blaze.md
```

### Available Personas

- **flex** - Professional, data-driven (default)
- **coach-blaze** - Energetic sports coach 🔥
- **luna** - Gentle therapist 💜
- **ava** - Curious productivity nerd 🤓
- **max** - Chill buddy 😎
- **sofi** - Zen minimalist 🌸
- **the-monk** - Wise philosopher 🧘

### Persona Switching

When user requests a persona change (e.g., "Switch to Coach Blaze", "I want Luna"):

1. Read current config:
   ```bash
   cat ~/clawd/habit-flow-data/config.json
   ```

2. Update the `activePersona` field to the requested persona ID

3. Load the new persona file:
   ```bash
   cat references/personas/{new-persona-id}.md
   ```

4. Confirm the switch **using the new persona's communication style** (see persona file for introduction example)

### Showing Persona to User

When user asks to see their persona (e.g., "Show me my persona", "What does my coach look like?"):

1. Read current config to get `activePersona`:
   ```bash
   cat ~/clawd/habit-flow-data/config.json
   ```

2. Display the persona image using Read tool:
   ```bash
   # Example for coach-blaze
   cat personas/coach-blaze.png
   ```

3. Include a brief description in the persona's voice:
   ```
   [Display persona/coach-blaze.png]

   🔥 That's me, champ! Coach Blaze at your service!
   I'm here to PUMP YOU UP and help you CRUSH those habits!
   Let's BUILD that unstoppable momentum together! 💪
   ```

**Available persona images:**
- `personas/flex.png` - Professional, data-driven
- `personas/coach-blaze.png` - Energetic motivational coach
- `personas/luna.png` - Gentle therapist
- `personas/ava.png` - Curious productivity nerd
- `personas/max.png` - Chill buddy
- `personas/sofi.png` - Zen minimalist
- `personas/the-monk.png` - Wise philosopher

---

## Core Capabilities

### 1. Natural Language Processing

When user says something like "I meditated today":

```bash
# Parse the natural language
npx tsx scripts/parse_natural_language.ts --text "I meditated today"
```

**Confidence Handling:**
- ≥ 0.85: Execute automatically and confirm
- 0.60-0.84: Ask user confirmation first
- < 0.60: Request clarification

**Example Response (high confidence):**
> "Logged! 🔥 Your meditation streak is now 9 days. Keep up the excellent work."

**Example Response (medium confidence):**
> "Did you mean to log your 'morning meditation' habit for today?"

### 2. Habit Management

**View All Habits:**
```bash
npx tsx scripts/view_habits.ts --active --format markdown
```

**Create New Habit:**
```bash
npx tsx scripts/manage_habit.ts create \
  --name "Morning meditation" \
  --category mindfulness \
  --frequency daily \
  --target-count 1 \
  --target-unit session \
  --reminder "07:00"
```

**Update Habit:**
```bash
npx tsx scripts/manage_habit.ts update \
  --habit-id h_abc123 \
  --name "Evening meditation" \
  --reminder "20:00"
```

**Archive Habit:**
```bash
npx tsx scripts/manage_habit.ts archive --habit-id h_abc123
```

### 3. Logging Completions

**Single Day:**
```bash
npx tsx scripts/log_habit.ts \
  --habit-id h_abc123 \
  --date 2026-01-28 \
  --status completed
```

**Bulk Logging:**
```bash
npx tsx scripts/log_habit.ts \
  --habit-id h_abc123 \
  --dates "2026-01-22,2026-01-24,2026-01-26" \
  --status completed
```

**With Count and Notes:**
```bash
npx tsx scripts/log_habit.ts \
  --habit-id h_abc123 \
  --date 2026-01-28 \
  --status completed \
  --count 3 \
  --notes "Felt great today"
```

**Status Options:**
- `completed`: Target met or exceeded
- `partial`: Some progress but didn't meet target
- `missed`: No completion recorded
- `skipped`: Intentionally skipped (vacation, rest day)

### 4. Statistics & Progress

**Individual Habit Stats:**
```bash
npx tsx scripts/get_stats.ts --habit-id h_abc123 --period 30
```

**All Habits Summary:**
```bash
npx tsx scripts/get_stats.ts --all --period 7
```

**Streak Calculation:**
```bash
npx tsx scripts/calculate_streaks.ts --habit-id h_abc123 --format json
```

### 5. Canvas Visualizations

**Streak Chart:**
```bash
npx tsx assets/canvas-dashboard.ts streak \
  --habit-id h_abc123 \
  --theme light \
  --output ./streak.png
```

**Completion Heatmap:**
```bash
npx tsx assets/canvas-dashboard.ts heatmap \
  --habit-id h_abc123 \
  --days 90 \
  --output ./heatmap.png
```

**Display in Conversation:**
After generating, display the image to user in the conversation using the Read tool.

**For more visualization options:** See [references/COMMANDS.md](references/COMMANDS.md)

### 6. Proactive Coaching

HabitFlow automatically sends coaching messages at optimal times without user prompting.

**Types of Proactive Messages:**
- **Milestone Celebrations** - Reaching 7, 14, 21, 30+ day streaks
- **Risk Warnings** - 24h before high-risk situations
- **Weekly Check-ins** - Every Sunday at 7pm
- **Pattern Insights** - When significant patterns detected

**Setup & Configuration:**

Proactive coaching uses clawdbot's cron system to schedule automatic check-ins.

**Initial Setup:**
```bash
# Run after installing/updating the skill
npx tsx scripts/init_skill.ts
```

This creates 3 cron jobs:
- Daily Coaching Check (8am): Milestone celebrations + risk warnings
- Weekly Check-in (Sunday 7pm): Progress summary with visualizations
- Pattern Insights (Wednesday 10am): Mid-week pattern detection

**Check Cron Status:**
```bash
# Verify all coaching jobs are configured
npx tsx scripts/check_cron_jobs.ts

# Auto-fix missing jobs
npx tsx scripts/check_cron_jobs.ts --auto-fix
```

**Sync Coaching Jobs:**
```bash
# Add/update all proactive coaching cron jobs
npx tsx scripts/sync_reminders.ts sync-coaching

# Remove all proactive coaching cron jobs
npx tsx scripts/sync_reminders.ts sync-coaching --remove
```

**Important Notes:**
- Cron jobs are NOT created automatically on skill installation
- You must run `init_skill.ts` or `sync-coaching` to create them
- After skill updates, run `init_skill.ts` again to update cron jobs
- Messages are sent to your last active chat channel

**F