Morning Routine

Overview

Automated start-of-day setup that ensures optimal development environment before starting work.

Core principle: Validate readiness to code and restore previous session context with zero manual overhead.

Trigger: Start of work day, after opening Claude Code

Duration: ~15-20 seconds (vs. ~90 seconds manual)

Ready to Code Score (0-100)

Comprehensive readiness check across 6 dimensions:

Check	Points	Criteria
Session Restored	20	Previous session context restored from STATUS.json
Services Healthy	20	All required dev services running
Dependencies Updated	15	Package dependencies up to date
Branches Synced	15	Local branch synced with remote
PRs Reviewed	15	No PRs waiting for review
Issues Triaged	15	All issues assigned/prioritized

Score Interpretation:

• 90-100: Excellent - Fully ready to code
• 80-89: Very Good - Almost ready, minor setup
• 70-79: Good - Ready with minor issues
• 60-69: Fair - 10-15 minutes setup needed
• 50-59: Poor - Significant setup required
• 0-49: Not Ready - Focus on environment setup

Workflow Steps

1. Restore Previous Session

Load context from STATUS.json:

from pathlib import Path
import json

status_file = Path('STATUS.json')
if status_file.exists():
    status = json.loads(status_file.read_text())

    # Extract session context
    last_nightly = status.get('last_nightly_routine', {})
    git_status = status.get('git_status', {})

    session_data = {
        'restored': True,
        'last_nightly_score': last_nightly.get('sleep_score'),
        'last_work_summary': git_status.get('action_required'),
        'previous_branch': git_status.get('current_branch'),
        'stashed_count': git_status.get('stashes', 0)
    }

Restored Context Includes:

• Last nightly routine Sleep Score
• Previous work summary
• Git branch and uncommitted work
• Stashed changes count

2. Check Dev Environment

Using capture_state.py utility with morning-specific checks:

from popkit_shared.utils.capture_state import capture_project_state

state = capture_project_state()
# Returns: {
#   'git': {...},
#   'github': {...},
#   'services': {...}
# }

Git Analysis:

• Current branch
• Commits behind remote (after git fetch)
• Uncommitted files
• Stashed changes

GitHub Analysis:

• PRs needing review (no review decision or changes requested)
• Issues needing triage (no assignee or labels)
• Latest CI status

Service Analysis:

• Running dev services (node, npm, pnpm, redis, postgres, supabase)
• Required services vs. running services

Dependency Analysis:

• Outdated package count
• Major/minor updates available

3. Calculate Ready to Code Score

Using ready_to_code_score.py module:

from pop_morning.scripts.ready_to_code_score import calculate_ready_to_code_score

score, breakdown = calculate_ready_to_code_score(state)
# score: 0-100
# breakdown: {
#   'session_restored': {'points': 20, 'max': 20, 'reason': '...'},
#   'services_healthy': {'points': 10, 'max': 20, 'reason': '...'},
#   ...
# }

4. Generate Morning Report

Using morning_report_generator.py module:

from pop_morning.scripts.morning_report_generator import generate_morning_report

report = generate_morning_report(score, breakdown, state)
# Returns formatted markdown report with:
# - Ready to Code Score headline
# - Score breakdown table
# - Service status (if not all running)
# - Setup recommendations
# - Today's focus items

5. Capture Session State

Update STATUS.json with morning routine data:

# This happens automatically via direct STATUS.json update
# Updates STATUS.json with:
# - Morning routine execution timestamp
# - Ready to Code score
# - Session restoration status
# - Dev environment state
# - Recommendations

6. Present Report to User

Display morning report with:

• Ready to Code Score (0-100) with visual indicator
• Score Breakdown - What contributed to the score
• Setup Issues - Services down, sync needed, outdated deps
• Recommendations - Actions before coding
• Today's Focus - PRs to review, issues to triage

Data Collection Commands

Git Commands (Consolidated)

Single command to gather all git data:

{
  git fetch --quiet
  echo "=== BRANCH ==="
  git rev-parse --abbrev-ref HEAD
  echo "=== BEHIND ==="
  git rev-list --count HEAD..origin/$(git rev-parse --abbrev-ref HEAD)
  echo "=== STATUS ==="
  git status --porcelain
  echo "=== STASHES ==="
  git stash list | wc -l
}

GitHub Commands (Consolidated)

{
  gh pr list --state open --json number,title,reviewDecision
  echo "---SEPARATOR---"
  gh issue list --state open --json number,title,assignees,labels
} > /tmp/gh_morning_data.json

Service Check (Consolidated)

{
  ps aux | grep -E "(node|npm|pnpm|redis|postgres|supabase)" | grep -v grep
  echo "---SEPARATOR---"
  pnpm outdated --json 2>/dev/null || echo "{}"
} > /tmp/service_morning_data.txt

Integration with Existing Utilities

capture_state.py

Located: packages/shared-py/popkit_shared/utils/capture_state.py

def capture_project_state() -> dict:
    """Capture complete project state for morning routine."""
    return {
        'git': capture_git_state(),
        'github': capture_github_state(),
        'services': capture_service_state(),
        'timestamp': datetime.now().isoformat()
    }

routine_measurement.py

Located: packages/shared-py/popkit_shared/utils/routine_measurement.py

When invoked with --measure flag:

• Tracks tool call count
• Measures duration
• Calculates token usage
• Saves to .claude/popkit/measurements/morning-<timestamp>.json

routine_cache.py

Located: packages/shared-py/popkit_shared/utils/routine_cache.py

Caching strategy:

• Never cache: Git status (changes frequently)
• Cache 5 min: Service status, dependency checks
• Cache 15 min: GitHub PR/issue data

Output Format

# ☀️ Morning Routine Report

**Date**: 2025-12-28 09:30
**Ready to Code Score**: 75/100 👍
**Grade**: B - Good - Ready with minor issues

## Score Breakdown

| Check | Points | Status |
|-------|--------|--------|
| Session Restored | 20/20 | ✅ Previous session context restored |
| Services Healthy | 10/20 | ⚠️ Missing: redis |
| Dependencies Updated | 15/15 | ✅ All dependencies up to date |
| Branches Synced | 10/15 | ⚠️ 3 commits behind remote |
| PRs Reviewed | 15/15 | ✅ No PRs pending review |
| Issues Triaged | 10/15 | ⚠️ 2 issues need triage |

## 🔧 Dev Services Status

**Required**: 2 services
**Running**: 1 services

**Not Running:**

- redis

## 🔄 Branch Sync Status

**Current Branch**: fix/critical-build-blockers
**Commits Behind Remote**: 3

Run `git pull` to sync with remote.

## 📋 Recommendations

**Before Starting Work:**
- Start dev services: redis
- Sync with remote: git pull (behind by 3 commits)

**Today's Focus:**
- Triage 2 open issues
- Review overnight commits and CI results
- Continue: Fix critical build blockers

---

STATUS.json updated ✅
Morning session initialized. Ready to code!

Error Handling

Git Not Available

try:
    git_state = capture_git_state()
except GitNotFoundError:
    print("[WARN] Git not available - skipping git checks")
    # Continue with partial score

GitHub CLI Not Available

try:
    github_state = capture_github_state()
except GhNotFoundError:
    print("[WARN] GitHub CLI not available - skipping GitHub checks")
    # Continue with partial score

Service Check Failures

# Service checks are best-effort
# If they fail, provide recommendations but don't block

Session Restore Failures

try:
    session_data = restore_session()
except Exception:
    print("[WARN] Could not restore session - starting fresh")
    session_data = {'restored': False}

Optimization Features

Tool Call Reduction

• Estimated Baseline: ~15 tool calls (manual)
• Optimized: ~5 tool calls (automated)
• Reduction: ~67%

Execution Time

• Estimated Baseline: ~90 seconds (manual, with thinking)
• Optimized: ~15-20 seconds (automated)
• Improvement: 78-83%

Caching

With --optimized flag:

• Uses routine_cache.py for GitHub/service data
• Reduces redundant API calls
• 40-96% token reduction (per routine.md)

Usage Examples

Basic Usage

/popkit:routine morning
# → Runs default morning routine
# → Calculates Ready to Code Score
# → Updates STATUS.json
# → Shows report

With Measurement

/popkit:routine morning --measure
# → Runs morning routine
# → Tracks performance metrics
# → Saves to .claude/popkit/measurements/

Quick Summary

/popkit:routine morning quick
# → Shows one-line summary
# → Ready to Code Score: 75/100 👍 - redis down, 3 commits behind

With Optimization

/popkit:routine morning --optimized
# → Uses caching for GitHub/service data
# → Reduces token usage by 40-96%

Files Modified

1. STATUS.json - Session state updated with:

   • Ready to Code score
   • Session restoration status
   • Dev environment state
   • Morning routine timestamp
   • Recommendations

2. .claude/popkit/measurements/ (if --measure used)

   • Performance metrics
   • Tool call breakdown
   • Duration and token usage

Related Skills

• pop-session-resume: Restores session context (invoked automatically)
• pop-nightly: Evening counterpart with Sleep Score
• pop-routine-optimized: Optimized execution with caching

Related Commands

• /popkit:routine morning: Main entry point
• /popkit:routine nightly: Nightly routine
• /popkit:next: Context-aware next action recommendations

Success Criteria

✅ Ready to Code Score accurately reflects environment state ✅ STATUS.json always updated correctly ✅ Completes in <25 seconds ✅ Provides actionable recommendations ✅ Session context successfully restored ✅ Reduces manual workflow by 67%

---

Skill Type: Automated Routine Category: Workflow Automation Tier: Core (Always Available) Version: 1.0.0