chronicle-project-tracker

What this skill does

# Chronicle Project Tracker

This skill helps you manage project development meta-state using Chronicle's built-in project tracking features. Use MCP tools for programmatic access or CLI commands for portability.

## Auto-Activation

> **This skill auto-activates!** (Milestone #13)
>
> Prompts like "what's next?" or "show roadmap" automatically trigger this skill. No manual loading needed!
>
> **Trigger patterns:** what's next, show roadmap, create milestone, track progress
> **See:** `docs/HOOKS.md` for full details

## When to Use This Skill

Use this skill when:
- Planning new features or milestones
- Tracking development progress
- Viewing project roadmap
- Linking sessions to milestones
- Checking what's in progress or planned
- Answering "what should I work on next?"
- Generating progress reports

## Available Tools (MCP + CLI)

### MCP Tools (Programmatic Access)

**Query Tools:**
- `mcp__chronicle__get_milestones(status, milestone_type, limit)` - List milestones
- `mcp__chronicle__get_milestone(milestone_id)` - Get milestone details
- `mcp__chronicle__get_next_steps(completed, milestone_id, limit)` - List next steps
- `mcp__chronicle__get_roadmap(days)` - View project roadmap

**Update Tools:**
- `mcp__chronicle__update_milestone_status(milestone_id, new_status)` - Update status
- `mcp__chronicle__complete_next_step(step_id)` - Mark step complete

### CLI Commands (Portable)

**See "CLI Commands Reference" section below for full list.**

Key commands:
- `chronicle milestones` - List milestones
- `chronicle roadmap` - View roadmap
- `chronicle next-steps` - List next steps
- `chronicle milestone-complete <id>` - Mark complete

## Workflow: Planning a New Feature

When user wants to add a new feature:

1. **Check existing roadmap** to avoid duplicates:
   ```python
   roadmap = mcp__chronicle__get_roadmap(days=30)
   # Review planned milestones
   ```

2. **Create milestone** via CLI (user runs this):
   ```bash
   chronicle milestone "Feature name" \
     --description "What it does" \
     --type feature \
     --priority 1 \
     --tags "phase-5,api,backend"
   ```

3. **Break down into next steps**:
   ```bash
   chronicle next-step "Design API endpoints" --priority 1 --effort medium --milestone <ID>
   chronicle next-step "Write tests" --priority 2 --effort small --milestone <ID>
   chronicle next-step "Document in README" --priority 3 --effort small --milestone <ID>
   ```

4. **Update status when starting work**:
   ```python
   mcp__chronicle__update_milestone_status(milestone_id=1, new_status="in_progress")
   ```

## Workflow: Session Linking

When completing a development session:

1. **Get session ID** from recent sessions:
   ```python
   sessions = mcp__chronicle__get_sessions(limit=5)
   latest_session_id = sessions[0]['id']
   ```

2. **Find active milestone**:
   ```python
   milestones = mcp__chronicle__get_milestones(status="in_progress")
   active_milestone_id = milestones[0]['id']
   ```

3. **Link them** (user runs this):
   ```bash
   chronicle link-session <session_id> --milestone <milestone_id>
   ```

4. **Complete next steps** as work progresses:
   ```python
   mcp__chronicle__complete_next_step(step_id=1)
   ```

## Workflow: Generating Progress Reports

When user asks "what did I accomplish this week?":

1. **Get roadmap**:
   ```python
   roadmap = mcp__chronicle__get_roadmap(days=7)
   ```

2. **Extract info**:
   - `roadmap['recently_completed']` - Milestones completed in last 7 days
   - `roadmap['in_progress']` - Current active work
   - `roadmap['summary']` - Statistics

3. **Get linked sessions** for each completed milestone:
   ```python
   for milestone in roadmap['recently_completed']:
       milestone_details = mcp__chronicle__get_milestone(milestone['id'])
       sessions = milestone_details['linked_sessions']
       # Summarize work done
   ```

4. **Format report** showing:
   - Completed milestones with linked sessions
   - Git commits from those sessions
   - Time spent (from session durations)
   - Key files modified

## Workflow: Viewing Roadmap

When user asks "what's next?" or "show me the roadmap":

```python
# Get full roadmap
roadmap = mcp__chronicle__get_roadmap(days=7)

# Present in organized format:
print("🚧 IN PROGRESS:")
for m in roadmap['in_progress']:
    print(f"  - {m['title']} ({len(m['related_sessions'])} sessions)")

print("\n📋 PLANNED (High Priority):")
for m in roadmap['planned_high_priority']:
    print(f"  - [P{m['priority']}] {m['title']}")

print("\n🔜 NEXT STEPS:")
for step in roadmap['pending_next_steps']:
    effort = f" [{step['estimated_effort']}]" if step['estimated_effort'] else ""
    print(f"  - [P{step['priority']}] {step['description']}{effort}")

print("\n✅ RECENTLY COMPLETED:")
for m in roadmap['recently_completed']:
    print(f"  - {m['title']} ({m['completed_at']})")
```

## Workflow: Completing a Milestone

When all work for a milestone is done:

1. **Verify all next steps completed**:
   ```python
   steps = mcp__chronicle__get_next_steps(milestone_id=<ID>, completed=False)
   if len(steps['next_steps']) == 0:
       # All done!
   ```

2. **Mark milestone complete** (user runs):
   ```bash
   chronicle milestone-complete <ID>
   ```

3. **Auto-generates documentation** by querying:
   ```python
   milestone = mcp__chronicle__get_milestone(<ID>)
   # Has all linked sessions, commits, duration
   # Can auto-update DEVELOPMENT_HISTORY.md or export to Obsidian
   ```

## Querying Examples

### "What features are in progress?"
```python
milestones = mcp__chronicle__get_milestones(status="in_progress")
for m in milestones['milestones']:
    sessions = len(m['related_sessions'])
    print(f"{m['title']}: {sessions} sessions so far")
```

### "What's the highest priority work?"
```python
roadmap = mcp__chronicle__get_roadmap()
top_planned = roadmap['planned_high_priority'][0]
print(f"Next up: {top_planned['title']} (P{top_planned['priority']})")
```

### "Show me all optimization work"
```python
milestones = mcp__chronicle__get_milestones(milestone_type="optimization")
```

### "What work did session 16 contribute to?"
```python
# Get all milestones
all_milestones = mcp__chronicle__get_milestones(limit=100)
for m in all_milestones['milestones']:
    if 16 in m['related_sessions']:
        print(f"Session 16 worked on: {m['title']}")
```

## Statistics & Reports

### Weekly Progress Report
```python
roadmap = mcp__chronicle__get_roadmap(days=7)

completed_count = len(roadmap['recently_completed'])
in_progress_count = len(roadmap['in_progress'])

print(f"Week of {date}:")
print(f"✅ {completed_count} milestones completed")
print(f"🚧 {in_progress_count} milestones in progress")
print(f"⏰ {roadmap['summary']['total_next_steps'] - roadmap['summary']['completed_next_steps']} pending tasks")
```

### Milestone Velocity
```python
# Get all completed milestones
completed = mcp__chronicle__get_milestones(status="completed", limit=100)

# Calculate average time from creation to completion
durations = []
for m in completed['milestones']:
    created = datetime.fromisoformat(m['created_at'])
    completed_at = datetime.fromisoformat(m['completed_at'])
    durations.append((completed_at - created).days)

avg_days = sum(durations) / len(durations)
print(f"Average milestone completion time: {avg_days:.1f} days")
```

## Auto-Documentation Pattern

Instead of manually updating DEVELOPMENT_HISTORY.md:

```python
# Query completed milestones
completed = mcp__chronicle__get_milestones(status="completed")

# For each milestone, get details
for milestone in completed['milestones']:
    details = mcp__chronicle__get_milestone(milestone['id'])

    # Extract:
    # - Title, description
    # - Related sessions (with summaries)
    # - Related commits (with messages)
    # - Duration (from session data)
    # - Files modified (from commits)

    # Generate markdown section
    md = f"### {details['title']}\n"
    md += f"{details['description']}\n\n"
    md += f"**Status**: {details['