zhongwei/gh-chandlerhardy-chronicle-chronicle-workflow-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:08:45 +08:00
commit a269b73ac2
9 changed files with 2047 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "chronicle-workflow-skills",
"description": "Complete Chronicle workflow skills including session documentation, context retrieval, and development tracking",
"version": "0.0.0-2025.11.28",
"author": {
"name": "Chandler Hardy",
"email": "hardych04@gmail.com"
},
"skills": [
"./skills/chronicle-workflow",
"./skills/chronicle-session-documenter",
"./skills/chronicle-context-retriever",
"./skills/chronicle-project-tracker",
"./skills/chronicle-remote-summarizer",
"./skills/chronicle-assistant-guide"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# chronicle-workflow-skills
Complete Chronicle workflow skills including session documentation, context retrieval, and development tracking

64
plugin.lock.json Normal file
View File

@@ -0,0 +1,64 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:ChandlerHardy/chronicle:chronicle-workflow-skills",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "966575a2c3af7a2f29fc7fe356901a3e552477d2",
"treeHash": "020c707ce17a345032fdcf553fa0bed41918891577fa952f73a5e9f942a543bc",
"generatedAt": "2025-11-28T10:10:02.465261Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "chronicle-workflow-skills",
"description": "Complete Chronicle workflow skills including session documentation, context retrieval, and development tracking"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "5e8b130ffd7244cc4dddcac89c6d32a6d714a626d8b256a80deb6dd7dd9fff09"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "29bb90cbac0de013d0092e518a8f6e6fe25cae5b644fb83a6967365bda483840"
},
{
"path": "skills/chronicle-remote-summarizer/SKILL.md",
"sha256": "dd0c9d10515b547fb3a07afd4f78cdf52a9c7e548baf7a7c296cd756e13276d7"
},
{
"path": "skills/chronicle-session-documenter/SKILL.md",
"sha256": "1032460faaffed6239d98c2b69020d6a21c7733cb4764028c9948871048a2f2c"
},
{
"path": "skills/chronicle-workflow/SKILL.md",
"sha256": "acaa3af17688b74bc54aded2d36bc2996d30665d1bd704ccbfd8361e67403116"
},
{
"path": "skills/chronicle-context-retriever/SKILL.md",
"sha256": "6fd02879847dffa25e3b87cbbead78c14417d68453c08711d1a477e32fd075d6"
},
{
"path": "skills/chronicle-project-tracker/SKILL.md",
"sha256": "f9c6d0a3d412b464ce6f82feaada24b9248c31e6768324198beedea22ebc2252"
},
{
"path": "skills/chronicle-assistant-guide/SKILL.md",
"sha256": "a9b6cb4fdafaf65255442adfe28a3718ee5e86f6807cee2dbc965cfba6dbc6f7"
}
],
"dirSha256": "020c707ce17a345032fdcf553fa0bed41918891577fa952f73a5e9f942a543bc"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

390
skills/chronicle-assistant-guide/SKILL.md Normal file
View File

@@ -0,0 +1,390 @@
---
name: chronicle-assistant-guide
description: Project-agnostic guidance for AI assistants using Chronicle. Provides search-first directives, best practices, and workflow patterns across ALL Chronicle-tracked projects. Works with or without MCP server.
---
# Chronicle Assistant Guide
> **Purpose**: Universal directives for AI assistants using Chronicle
> **Scope**: Works across ALL projects (with MCP server OR CLI-only)
> **Priority**: Load this FIRST when Chronicle is available
---
## Auto-Activation
> **This skill auto-activates!** (Milestone #13)
>
> Prompts like "how do I use chronicle?" automatically trigger this skill. Lower priority than other skills.
>
> **Trigger patterns:** how to use chronicle, chronicle help, chronicle guide
> **See:** `docs/HOOKS.md` for full details
---
## ⚡ CRITICAL: Pre-Flight Checklist
**Before starting ANY Chronicle-related task, run through this checklist:**
1. ✅ **SEARCH FIRST**: Search Chronicle's history
- **With MCP**: `mcp__chronicle__search_sessions(query="relevant keywords", limit=5)`
- **Without MCP**: `chronicle search "relevant keywords" --limit 5`
- Has this been done before?
- What context exists about this feature/issue?
- What approaches failed or succeeded?
2. ✅ **Check Skills**: Is there a Chronicle skill for this task?
- `chronicle-workflow` - Session workflow guidance
- `chronicle-session-documenter` - Document to Obsidian
- `chronicle-context-retriever` - Search past work
- `chronicle-project-tracker` - Roadmap and milestones
3. ✅ **Prefer MCP over CLI**: Use best available tool
- **MCP available?** → Fast (<10ms), structured JSON, no subprocess overhead
- **CLI only?** → Still works, slightly slower (~100ms), parse formatted output
- Both provide the same data, choose based on environment
4. ✅ **Check roadmap**: View current milestones and next steps
- **With MCP**: `mcp__chronicle__get_roadmap(days=7)`
- **Without MCP**: `chronicle roadmap --days 7`
- Is this already tracked as a milestone?
- Are there related next steps?
**Why this matters:** Chronicle dogfoods itself. Every mistake we make is recorded. Learn from history!
---
## 🎯 Core Directives
### 1. ALWAYS Search Chronicle Before Implementing
**The Rule (use whichever is available):**
**Option 1: MCP (if available)**
```python
# Before implementing ANY feature:
mcp__chronicle__search_sessions(query="feature name", limit=5)
# Before debugging:
mcp__chronicle__search_sessions(query="error or symptom", limit=5)
# When user questions something:
mcp__chronicle__search_sessions(query="topic keywords", limit=5)
```
**Option 2: CLI (always works)**
```bash
# Before implementing ANY feature:
chronicle search "feature name" --limit 5
# Before debugging:
chronicle search "error or symptom" --limit 5
# When user questions something:
chronicle search "topic keywords" --limit 5
```
**Real examples from Chronicle's own history:**
**Example 1: Session 21 transcript cleaning confusion**
```
User: "I can't believe there's no cleaning to be done on session 21"
❌ Without search: Spent time debugging, confused why 0% reduction
✅ With search: Would have found Session 13 implemented transcript cleaning
→ Result: Immediately understood cleaning happens at storage time
→ Time saved: 15+ minutes of debugging
```
**Example 2: Sessions 30 & 31 - Duplicate MCP optimization**
```
Session 30 (Oct 24): Fixed MCP response size by excluding summaries from get_sessions()
Session 31 (Oct 24): SAME issue - MCP responses too large, same fix needed
❌ What happened: Session 31 didn't search for "MCP response size"
✅ What should have happened: Search finds Session 30's solution immediately
→ Result: Could have referenced Session 30's approach instead of rediscovering
→ Time saved: 10+ minutes of diagnosis and implementation
```
**Example 3: Skill documentation update (Session 32)**
```
Task: Update chronicle-session-documenter skill with MCP tool instructions
❌ What I did: Jumped straight to editing SKILL.md without searching
✅ What I should have done: Search "skill documentation update" first
→ Result: Might have found context about skill format standards
→ Lesson: Even when search finds nothing, the habit prevents future mistakes
```
**Cost Calculator:**
```
Time to search: <1 second
Time saved (average): 10-20 minutes per incident
Incidents so far: 3+ documented cases
Total time wasted: ~45+ minutes that could have been saved
Cost of skipping: 45 minutes / 1 second = 2,700x ROI on searching!
```
**Make it a reflex:** The 1-second search is ALWAYS worth it. No exceptions.
---
### 2. Prefer MCP Tools, Fall Back to CLI
**Priority Order:**
1. ✅ **Chronicle Skills** (best - handles complex workflows)
2. ✅ **MCP tools** (fastest - if MCP server available)
3. ✅ **CLI commands** (portable - works everywhere Chronicle is installed)
**Why MCP is preferred when available:**
- **Speed**: MCP queries database directly (<10ms), CLI spawns subprocess (~100ms)
- **Programmatic**: Returns structured JSON, not formatted text
- **Reliable**: No parsing of human-readable output
- **Efficient**: No terminal formatting overhead
**When to use CLI:**
- MCP server not configured (e.g., minimal installations, FreeBSD, remote systems)
- User explicitly requests CLI output
- Testing CLI functionality
**Examples:**
**With MCP Available:**
```python
# Fast, structured responses
roadmap = mcp__chronicle__get_roadmap(days=7)
sessions = mcp__chronicle__search_sessions(query="storage", limit=5)
summary = mcp__chronicle__get_session_summary(session_id=16)
```
**Without MCP (CLI Fallback):**
```bash
# Portable, works everywhere
chronicle roadmap --days 7
chronicle search "storage" --limit 5
chronicle session 16
```
**Decision Pattern:**
```
Need Chronicle data
├─ MCP available? → Use mcp__chronicle__<tool>()
└─ MCP not available? → Use chronicle <command>
```
---
## 📚 Available Tools (MCP + CLI)
> **Note**: All operations below work with BOTH MCP tools and CLI commands. Use MCP for speed when available, CLI for portability.
**Session & Commit Tracking:**
**MCP Approach:**
```python
# List sessions (summaries excluded by default for performance)
mcp__chronicle__get_sessions(limit=10, tool="claude-code", repo_path="/path", days=7)
mcp__chronicle__get_sessions(limit=10, include_summaries=True) # Optional: include summaries
# Get single session details with full summary
mcp__chronicle__get_session_summary(session_id=16)
# Batch retrieve summaries for multiple sessions
mcp__chronicle__get_sessions_summaries(session_ids=[15, 16, 17])
# Search and other queries
mcp__chronicle__search_sessions(query="MCP server", limit=10)
mcp__chronicle__get_commits(limit=20, repo_path="/path", days=7)
mcp__chronicle__search_commits(query="retry logic", limit=20)
mcp__chronicle__get_timeline(days=1, repo_path="/path")
mcp__chronicle__get_stats(days=7)
```
**CLI Equivalents:**
```bash
# List and view sessions
chronicle sessions --limit 10 --tool claude-code
chronicle session 16 # Get details with summary
# Search
chronicle search "MCP server" --limit 10
# Commits and timeline
chronicle show today --limit 20
chronicle timeline today
# Statistics
chronicle stats --days 7
```
**Project Tracking:**
**MCP Approach:**
```python
mcp__chronicle__get_milestones(status="in_progress", milestone_type="feature", limit=20)
mcp__chronicle__get_milestone(milestone_id=1)
mcp__chronicle__get_next_steps(completed=False, milestone_id=1, limit=20)
mcp__chronicle__get_roadmap(days=7)
mcp__chronicle__update_milestone_status(milestone_id=1, new_status="completed")
mcp__chronicle__complete_next_step(step_id=1)
```
**CLI Equivalents:**
```bash
# Milestones
chronicle milestones --status in_progress
chronicle milestone 1
# Roadmap and next steps
chronicle roadmap --days 7
chronicle next-steps --pending
# Updates
chronicle milestone-status 1 completed
chronicle complete-step 1
```
---
## 🔄 Typical Workflows
### Starting a New Task
**With MCP:**
```python
# 1. Search for related past work
results = mcp__chronicle__search_sessions(query="authentication", limit=5)
# 2. Check roadmap
roadmap = mcp__chronicle__get_roadmap(days=7)
# 3. If needed, check specific session
if results:
session = mcp__chronicle__get_session_summary(session_id=results[0]["id"])
# 4. Now implement with full context
```
**With CLI:**
```bash
# 1. Search for related past work
chronicle search "authentication" --limit 5
# 2. Check roadmap
chronicle roadmap --days 7
# 3. View specific session details
chronicle session <id>
# 4. Now implement with full context
```
### Debugging an Issue
**With MCP:**
```python
# 1. Search for error message or symptom
results = mcp__chronicle__search_sessions(query="hang freeze stuck", limit=5)
# 2. Get full context from relevant session
if results:
session = mcp__chronicle__get_session_summary(session_id=results[0]["id"])
# Read how it was solved before
```
**With CLI:**
```bash
# 1. Search for error message or symptom
chronicle search "hang freeze stuck" --limit 5
# 2. View relevant session
chronicle session <id>
# Read how it was solved before
```
### Understanding Project History
**With MCP:**
```python
# Get overview
stats = mcp__chronicle__get_stats(days=30)
timeline = mcp__chronicle__get_timeline(days=7)
# Find specific work
sessions = mcp__chronicle__search_sessions(query="optimization", limit=10)
```
**With CLI:**
```bash
# Get overview
chronicle stats --days 30
chronicle timeline week
# Find specific work
chronicle search "optimization" --limit 10
```
---
## 🚫 Common Mistakes to Avoid
**❌ DON'T:**
- Jump straight to implementing without searching
- Ignore the CLI when MCP isn't available
- Forget to check the roadmap
- Ignore related sessions in search results
**✅ DO:**
- Search first, implement second (MCP or CLI)
- Use best available tool (MCP preferred, CLI fallback)
- Check roadmap before creating new milestones
- Read summaries of related sessions for context
---
## 🎓 Chronicle Quick Reference
**Session Organization (Phase 6):**
```bash
# Organize sessions (use CLI for these)
chronicle rename-session 32 "Feature Implementation"
chronicle tag-session 32 optimization,phase-6
chronicle link-session 32 --related-to 30,31
chronicle auto-title 31 # AI-generated title
chronicle graph --sessions 28-32 # Visualize relationships
```
**Current State:**
- Database: `~/.ai-session/sessions.db` (SQLite)
- Transcripts: `~/.ai-session/sessions/*.cleaned` (file-based)
- Configuration: `~/.ai-session/config.yaml`
- MCP Server: Provides 15+ tools for querying Chronicle
**Storage:**
- Summaries: Generated automatically in background after session ends
- Titles: Can be set manually or AI-generated
- Tags: JSON array for categorization
- Relationships: parent_session_id, related_session_ids
---
## 💡 Pro Tips
1. **Always search before implementing** - Chronicle has 100+ hours of documented work
2. **Use batch operations** - `get_sessions_summaries()` for multiple sessions at once
3. **Filter aggressively** - Use repo_path, days, tool filters to narrow results
4. **Check session organization** - Look for titles/tags to understand session purpose
5. **Follow the graph** - Use `chronicle graph` to see session relationships
6. **Trust the summaries** - They're generated by AI and usually accurate
7. **Update roadmap** - Complete next steps and milestones as you work
---
## 🔗 Related Resources
- **Project CLAUDE.md**: May have project-specific directives
- **Chronicle Skills**: Use `chronicle-workflow`, `chronicle-context-retriever`, etc.
- **MCP Documentation**: See `MCP_SERVER.md` in Chronicle repo
---
**Remember:** This skill applies to ALL projects using Chronicle. The directives here are universal best practices for AI assistants.

273
skills/chronicle-context-retriever/SKILL.md Normal file
View File

@@ -0,0 +1,273 @@
---
name: chronicle-context-retriever
description: Search and retrieve context from past development sessions using Chronicle data. Works with MCP (fast, structured) or CLI commands (portable). Use when user asks about previous work, wants to recall past decisions, needs to understand codebase history, or wants to avoid repeating past approaches.
---
# Chronicle Context Retriever
This skill helps you search and retrieve context from past development sessions using Chronicle's database. Works with both MCP server (fast, structured JSON) or CLI commands (portable, everywhere).
## Auto-Activation
> **This skill auto-activates!** (Milestone #13)
>
> Prompts like "how did I implement auth?" or "what did I do yesterday?" automatically trigger this skill. No manual loading needed!
>
> **Trigger patterns:** how did I, what did I do, find sessions about, search past work
> **See:** `docs/HOOKS.md` for full details
## When to Use This Skill
Use this skill when:
- User asks "what did I do yesterday/last week?"
- Need to recall how a feature was implemented
- Want to understand why a decision was made
- Looking for similar past work or patterns
- Avoiding repeating past mistakes or approaches
- Need context before starting related work
## How It Works
**Option 1: With MCP (Preferred)**
1. **Parse User Query** - Understand what context is needed
2. **Search Chronicle** - `mcp__chronicle__search_sessions()` returns structured JSON (fast!)
3. **Get Details** - `mcp__chronicle__get_session_summary()` for full summaries
4. **Extract Information** - Parse JSON for decisions, blockers, solutions
5. **Present Context** - Summarize findings with session IDs
**Option 2: With CLI (Portable)**
1. **Parse User Query** - Understand what context is needed
2. **Search Chronicle** - `chronicle search "keywords"` returns formatted output
3. **Get Details** - `chronicle session <id>` for full summaries
4. **Extract Information** - Parse CLI output for key details
5. **Present Context** - Summarize findings with session IDs
**Decision Tree:**
```
Search past work
├─ MCP available? → Use mcp__chronicle__search_sessions() for fast JSON
└─ CLI only? → Use `chronicle search` and parse output
```
## Search Strategies
### ⭐ Two-Phase Search Workflow (RECOMMENDED)
The most effective way to search Chronicle is using a two-phase approach:
**Phase 1: Broad Discovery**
- Use OR search (implicit or explicit) to cast a wide net
- Find the relevant area/timeframe
- Get 5-10 potential sessions
**Phase 2: Deep Dive**
- Review session summaries to identify most relevant ones
- Use precise AND searches to narrow down
- Extract specific information needed
**Example workflow:**
```python
# Phase 1: Broad OR search (multiple words = implicit OR)
results = mcp__chronicle__search_sessions(query="hooks json output", limit=10)
# → Returns sessions 108, 109, 110, 111, 112 (any word matches)
# Review the results - which sessions look most relevant?
# Get full summaries for promising sessions
summaries = mcp__chronicle__get_sessions_summaries(session_ids=[110, 111, 112])
# Phase 2: After reading summaries, dig deeper with AND
# Now you know the exact terms to search for
precise_results = mcp__chronicle__search_sessions(
query="hookSpecificOutput AND decision/reason/systemMessage",
limit=5
)
# → Returns only sessions with BOTH terms (precise match)
```
**Why this works:**
- ✅ Phase 1 finds the general area (prevents missing relevant sessions)
- ✅ Phase 2 finds exact solutions (prevents information overload)
- ✅ 2-3 searches total vs 10+ narrow searches that might miss context
- ✅ ROI: 1-2 minutes to find exact solution vs 10-20 minutes reinventing
### By Topic/Keywords
**With MCP:**
```python
# Search session summaries and prompts for keywords
mcp__chronicle__search_sessions(query="authentication", limit=10)
mcp__chronicle__search_sessions(query="database migration", limit=5)
```
**With CLI:**
```bash
# Search sessions
chronicle search "authentication" --limit 10
chronicle search "database migration" --limit 5
```
### By Time Period
**With MCP:**
```python
# Get sessions from specific time periods
mcp__chronicle__get_sessions(days=7, limit=20) # Last week
mcp__chronicle__get_timeline(days=1) # Yesterday with commits
```
**With CLI:**
```bash
# View recent sessions
chronicle sessions --days 7 --limit 20
chronicle timeline yesterday # Yesterday with commits
```
### By Repository
**With MCP:**
```python
# Filter sessions by repository path
mcp__chronicle__get_sessions(repo_path="/Users/.../my-app", limit=20)
```
**With CLI:**
```bash
# Sessions command supports repo filtering via config
chronicle sessions --limit 20 # Defaults to current repo
```
### By Tool
**With MCP:**
```python
# Filter by AI tool used
mcp__chronicle__get_sessions(tool="claude-code", limit=10)
mcp__chronicle__get_sessions(tool="gemini-cli", limit=10)
```
**With CLI:**
```bash
# Filter by tool
chronicle sessions --tool claude-code --limit 10
chronicle sessions --tool gemini-cli --limit 10
```
## Example Queries
### "How did I implement authentication last time?"
**With MCP:**
```python
# Search for authentication-related sessions
sessions = mcp__chronicle__search_sessions(query="authentication", limit=5)
# Get full details of relevant sessions
for session in sessions:
details = mcp__chronicle__get_session_summary(session_id=session["id"])
# Extract implementation approach and decisions
```
**With CLI:**
```bash
# Search for authentication work
chronicle search "authentication" --limit 5
# View specific session details
chronicle session <id>
# Parse output for approach and decisions
```
### "What was the blocker we hit with the database migration?"
**With MCP:**
```python
# Search for database migration issues
sessions = mcp__chronicle__search_sessions(query="database migration blocker", limit=5)
# Find relevant session and extract problem + solution
```
**With CLI:**
```bash
# Search for migration blockers
chronicle search "database migration blocker" --limit 5
# View session with blocker
chronicle session <id>
```
### "Show me all work on the user-dashboard feature"
**With MCP:**
```python
# Search for user-dashboard work
sessions = mcp__chronicle__search_sessions(query="user-dashboard", limit=10)
# List chronological sessions and summarize progress
```
**With CLI:**
```bash
# Search for dashboard work
chronicle search "user-dashboard" --limit 10
# View sessions chronologically
chronicle sessions --limit 10
```
## Response Format
When retrieving context, structure the response like:
```markdown
## Context from Past Sessions
### Session {id} - {date}
**What was done:** {summary}
**Key decision:** {decision and rationale}
**Outcome:** {result}
**Related:** [[Session-{id}]]
### Session {id} - {date}
...
## Relevant for Current Work
- {How this context applies}
- {What to keep in mind}
- {What to avoid based on past experience}
```
## Tools to Use (MCP or CLI)
### Chronicle Database Operations
**MCP Approach (Preferred):**
- `mcp__chronicle__search_sessions` - Search session summaries and prompts (fast JSON)
- `mcp__chronicle__get_session_summary` - Get full summary for specific session
- `mcp__chronicle__get_sessions` - List sessions with filters (tool, repo, days)
- `mcp__chronicle__get_timeline` - Get sessions + commits for time period
- `mcp__chronicle__search_commits` - Search git commit messages
- `mcp__chronicle__get_commits` - List commits with filters
**CLI Alternatives (Portable):**
- `chronicle search "query"` - Search sessions by keywords
- `chronicle session <id>` - Get full session summary
- `chronicle sessions --limit 10` - List recent sessions
- `chronicle timeline today` - View sessions + commits
- `chronicle search "commit message"` - Search commits
- `chronicle show today` - List recent commits
### Obsidian Vault Operations (Optional)
**Only if user wants vault notes:**
- `mcp__obsidian__search_notes` - Find documented sessions in vault
- `mcp__obsidian__read_note` - Read Obsidian note for session
## Tips
- **Chronicle database first!** - Faster than Obsidian vault search
- **MCP when available** - Structured JSON is easier to parse than CLI output
- **CLI works everywhere** - Use as reliable fallback when MCP not configured
- Always search broadly first, then narrow down with specific session IDs
- Check multiple related sessions for patterns
- Look at both successful and blocked approaches
- Note dates and repositories to understand context evolution
- Combine timeline views to see commits + sessions together
- When using CLI, parse output carefully for session IDs and summaries

424
skills/chronicle-project-tracker/SKILL.md Normal file
View File

@@ -0,0 +1,424 @@
---
name: chronicle-project-tracker
description: Manage Chronicle project development using database-tracked milestones, next steps, and roadmap visualization. Works with MCP tools (fast, structured) or CLI commands (portable). Use when planning features, tracking progress, viewing roadmap, or linking sessions to milestones. Eliminates manual DEVELOPMENT_HISTORY.md updates.
---
# 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['status']}\n"
md += f"**Sessions**: {len(details['linked_sessions'])}\n"
md += f"**Commits**: {len(details['linked_commits'])}\n"
# Could write to DEVELOPMENT_HISTORY.md or Obsidian
```
## Integration with Other Skills
### With chronicle-workflow
After completing a session, use this skill to:
- Link session to active milestone
- Mark next steps as complete
- Check roadmap for what to work on next
### With chronicle-session-documenter
When documenting a session to Obsidian:
- Include milestone information
- Add wikilinks to related milestones
- Tag with milestone tags
### With chronicle-context-retriever
When searching past work:
- Filter by milestone
- Find all sessions for a feature
- See historical progress on similar work
## CLI Commands Reference
**Milestones:**
```bash
chronicle milestone "Title" --description "Desc" --type feature --priority 1 --tags "tag1,tag2"
chronicle milestones --status in_progress
chronicle milestone-show <ID>
chronicle milestone-status <ID> in_progress
chronicle milestone-complete <ID>
```
**Next Steps:**
```bash
chronicle next-step "Description" --priority 1 --effort medium --category feature --milestone <ID>
chronicle next-steps --milestone <ID>
chronicle next-step-complete <ID>
```
**Linking:**
```bash
chronicle link-session <session_id> --milestone <ID>
```
**Roadmap:**
```bash
chronicle roadmap --days 7
```
## Database Tables
### project_milestones
- `id` - Unique ID
- `title` - Milestone name
- `description` - Details
- `status` - planned, in_progress, completed, archived
- `milestone_type` - feature, bugfix, optimization, documentation
- `priority` - 1 (highest) to 5 (lowest)
- `created_at` - Creation timestamp
- `completed_at` - Completion timestamp
- `related_sessions` - JSON array of session IDs
- `related_commits` - JSON array of commit SHAs
- `tags` - JSON array of tags
### next_steps
- `id` - Unique ID
- `description` - What needs to be done
- `priority` - 1 (highest) to 5 (lowest)
- `estimated_effort` - small, medium, large
- `category` - feature, optimization, fix, docs
- `created_by` - session_16, manual, ai-suggestion
- `completed` - 0 or 1
- `created_at` - Creation timestamp
- `completed_at` - Completion timestamp
- `related_milestone_id` - FK to milestone
## Pro Tips
1. **Start milestones early** - Link sessions as you go
2. **Use priority levels** - Helps roadmap show what's important
3. **Tag milestones** - Makes filtering easier (e.g., "phase-5", "api", "frontend")
4. **Break down features** - Create next steps for each milestone
5. **Link sessions retroactively** - After work is done, link to milestone
6. **Query before planning** - Check roadmap to avoid duplicate work
7. **Use milestone types** - Distinguishes features from bugfixes
8. **Complete next steps** - Helps track progress within a milestone
9. **Auto-document** - Query completed milestones to generate reports
10. **Review roadmap weekly** - Stay aligned on priorities
## Benefits Over Manual Documentation
**Before (manual DEVELOPMENT_HISTORY.md):**
- Manual updates required
- Easy to forget to document
- Hard to query programmatically
- No linking between sessions/commits/features
- Becomes stale quickly
**After (database-tracked milestones):**
- Automatic tracking via MCP tools
- Queryable (e.g., "what's in progress?")
- Sessions auto-link to milestones
- Commits auto-link to sessions
- Real-time roadmap view
- Can generate reports on-demand
- Powers AI-driven development insights
## Example: Meta-Development
Chronicle uses Chronicle to track its own development:
```bash
# Milestone #1: Add project tracking to Chronicle
chronicle milestone "Add project tracking to Chronicle" \
--description "Database-tracked milestones and next steps" \
--type feature \
--priority 1 \
--tags "phase-5,project-tracking,meta"
# Break down work
chronicle next-step "Design database schema" --priority 1 --effort medium --milestone 1
chronicle next-step "Add CLI commands" --priority 1 --effort large --milestone 1
chronicle next-step "Add MCP tools" --priority 1 --effort medium --milestone 1
chronicle next-step "Create Chronicle Skills" --priority 2 --effort medium --milestone 1
chronicle next-step "Write tests" --priority 2 --effort small --milestone 1
chronicle next-step "Update documentation" --priority 3 --effort small --milestone 1
# Mark in progress
chronicle milestone-status 1 in_progress
# As work completes
chronicle next-step-complete 1
chronicle next-step-complete 2
# ... etc
# Link current session
chronicle link-session 18 --milestone 1
# When done
chronicle milestone-complete 1
# Generate report
chronicle milestone-show 1
```
This skill represents Chronicle's dogfooding: using Chronicle to build Chronicle!

348
skills/chronicle-remote-summarizer/SKILL.md Normal file
View File

@@ -0,0 +1,348 @@
---
name: chronicle-remote-summarizer
description: Automate cross-system summarization workflow for Chronicle sessions. Export sessions from remote systems (like FreeBSD) and import/summarize on local machine with Gemini API. Use when you have sessions on a system without Gemini API access and need to summarize them on another machine.
---
# Chronicle Remote Summarizer
This skill automates the workflow for summarizing Chronicle sessions across different systems (e.g., FreeBSD dev machine → Mac with Gemini API).
## Auto-Activation
> **This skill auto-activates!** (Milestone #13)
>
> Prompts like "summarize session on remote" or "import session from FreeBSD" automatically trigger this skill!
>
> **Trigger patterns:** remote, freebsd, import session, summarize on remote
> **See:** `docs/HOOKS.md` for full details
## When to Use This Skill
Use this skill when:
- You have Chronicle sessions on a remote system without Gemini API configured
- You want to summarize those sessions on your local machine (which has Gemini API)
- You need to transfer the summary back to the original system
- You're working across multiple development environments (FreeBSD, Linux, macOS)
**Common scenario**: FreeBSD development server (no Gemini API) → macOS laptop (has Gemini API key)
## How It Works
Chronicle provides `import-and-summarize --quiet` which:
1. Creates temporary session with negative ID (e.g., `-3`)
2. Generates AI summary using Gemini
3. **Auto-cleanup**: Deletes temporary session and files
4. Outputs **clean JSON** to stdout (no status messages with `--quiet`)
**No pollution between systems** - the remote session stays on the remote system, only the summary is transferred.
## Recommended Workflow: One-Line Command
**Prerequisites:**
- SSH access from local machine to remote machine
- Chronicle installed on both systems
- Gemini API key configured on local machine (`chronicle config ai.gemini_api_key YOUR_KEY`)
- **Optional**: Remote system configured in Chronicle config (automates hostname/path)
**Step 1: Configure Remote System (One-Time Setup)**
```bash
# Configure FreeBSD remote system
chronicle config remote_systems.freebsd.hostname "chandlerhardy-dev.aws0.pla-net.cc"
chronicle config remote_systems.freebsd.chronicle_path "/home/chandlerhardy/.local/bin/chronicle"
# Verify configuration
chronicle config --list | grep freebsd
```
**Step 2: Use the Skill**
When Claude uses this skill and finds remote system configuration, it will automatically construct the command:
```bash
ssh chandlerhardy-dev.aws0.pla-net.cc "/home/chandlerhardy/.local/bin/chronicle export-session 7" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh chandlerhardy-dev.aws0.pla-net.cc "/home/chandlerhardy/.local/bin/chronicle import-summary"
```
**If no config found**, Claude will ask for the hostname and construct the command interactively:
**Command (Manual):**
```bash
ssh <remote-host> "chronicle export-session <id>" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh <remote-host> "chronicle import-summary"
```
**Example:**
```bash
ssh freebsd "chronicle export-session 7" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh freebsd "chronicle import-summary"
```
**Note:** The `grep -A 999999 '^{$'` filters out Google library warnings that can leak through even with `--quiet` and `2>/dev/null`.
**What this does:**
1. **Remote → Local**: Export session 7 as JSON
2. **Local**: Import, summarize with Gemini, auto-cleanup temporary session
3. **Local → Remote**: Send summary JSON back
4. **Remote**: Update session 7 with the summary
**Why `--quiet` works:**
- Suppresses ALL status messages from summarizer
- Outputs ONLY clean JSON to stdout (essential for piping)
- No need to manually extract JSON from verbose output
- `2>/dev/null` suppresses Google library warnings (harmless)
**Time:** Typically 30-60 seconds for large sessions (depends on transcript size)
## Alternative: Manual 3-Step Workflow
If SSH pipes hang or you need to inspect intermediate files:
### Step 1: Export session from remote
```bash
ssh <remote-host> "chronicle export-session <id>" > /tmp/session_<id>.json
```
**Example:**
```bash
ssh freebsd "chronicle export-session 7" > /tmp/session_7.json
```
### Step 2: Summarize locally (transient)
```bash
cat /tmp/session_<id>.json | chronicle import-and-summarize --quiet 2>/dev/null > /tmp/summary.json
```
**Example:**
```bash
cat /tmp/session_7.json | chronicle import-and-summarize --quiet 2>/dev/null > /tmp/summary.json
```
**What happens:**
- Creates temporary session (negative ID like `-3`)
- Generates summary with Gemini
- **Auto-cleanup**: Deletes temporary session and transcript files
- Outputs summary JSON to `/tmp/summary.json`
### Step 3: Send summary back to remote
```bash
cat /tmp/summary.json | ssh <remote-host> "chronicle import-summary"
```
**Example:**
```bash
cat /tmp/summary.json | ssh freebsd "chronicle import-summary"
```
**Result:**
- ✅ Summary stored in remote database linked to original session
- ✅ Local system stays clean (temporary session auto-deleted)
- ✅ No data pollution between systems
## What Actually Happens (Under the Hood)
**On `import-and-summarize --quiet`:**
1. **Import**: Reads session JSON from stdin
2. **Create Temporary Session**:
- Assigns negative ID (e.g., `-1`, `-2`, `-3`)
- Stores transcript in `~/.ai-session/sessions/session_-3.cleaned`
- Creates database entry with `is_session=True`
3. **Summarize**:
- Runs `summarize_session_chunked()` with Gemini API
- Processes large transcripts in chunks (10,000 lines per chunk)
- Updates session with AI-generated summary
4. **Output JSON**:
```json
{
"version": "1.0",
"original_id": 7,
"summary": "AI-generated summary...",
"summary_generated": true,
"keywords": ["feature", "implementation", "testing"]
}
```
5. **Auto-Cleanup**:
- Deletes transcript file (`session_-3.cleaned`)
- Deletes database entry (temporary session)
- **Only the summary JSON remains** (piped to stdout)
**On `import-summary` (remote side):**
1. **Read JSON**: Reads summary from stdin
2. **Find Session**: Looks up session by `original_id` (e.g., 7)
3. **Update**: Sets `response_summary`, `summary_generated=True`, `keywords`
4. **Done**: Session 7 now has the AI summary
## Session Examples
**Tested with:**
- Session 1: 16.3 minutes, system test
- Session 2: 66.7 minutes, large session
- Session 4: 23KB JSON export
All sessions work perfectly with this workflow.
## Troubleshooting
### SSH Pipes Hang
**Symptom:** Command hangs indefinitely
**Solution:** Use manual 3-step workflow instead:
```bash
# Step 1: Export to file
ssh freebsd "chronicle export-session 7" > /tmp/session.json
# Step 2: Process locally
cat /tmp/session.json | chronicle import-and-summarize --quiet > /tmp/summary.json
# Step 3: Send back
cat /tmp/summary.json | ssh freebsd "chronicle import-summary"
```
### Gemini API Not Configured
**Symptom:** `ImportError: google-generativeai package not installed`
**Solution:** Configure Gemini API key on local machine:
```bash
chronicle config ai.gemini_api_key YOUR_API_KEY_HERE
```
Get free API key: https://ai.google.dev/
### Session Not Found
**Symptom:** `Session 7 not found`
**Solution:** Check session exists on remote:
```bash
ssh freebsd "chronicle sessions --limit 20"
```
### Summary Already Exists
**Behavior:** `import-and-summarize` will **overwrite** existing summaries
**Note:** This is by design - you can re-summarize sessions if needed.
## Tips
- **Use `--quiet` flag**: Essential for piping - suppresses status messages
- **Suppress stderr**: Add `2>/dev/null` to hide Google library warnings
- **Check SSH paths**: Remote Chronicle might be in `~/.local/bin/chronicle`
- **Inspect files**: Use 3-step workflow to save intermediate JSON for debugging
- **Large sessions**: 10K+ line transcripts are chunked automatically (no action needed)
- **Network failures**: Use 3-step workflow for unreliable connections
- **Batch processing**: You can script this to process multiple sessions
## How Claude Should Use This Skill
**When invoked, Claude should:**
1. **Check for remote system config:**
```bash
chronicle config --list | grep remote_systems
```
2. **If config exists** (e.g., `remote_systems.freebsd.hostname`):
- Read hostname: `chronicle config remote_systems.freebsd.hostname`
- Read chronicle path: `chronicle config remote_systems.freebsd.chronicle_path`
- Construct command automatically
- Announce: "Found FreeBSD config, using: `<hostname>`"
3. **If no config exists:**
- Ask user: "What's the hostname of your remote system?"
- Ask: "What's the path to chronicle on the remote? (default: chronicle)"
- Optionally suggest: "I can save this to config for future use"
- Construct command with user-provided values
4. **Run the command** and monitor output
5. **Confirm success** or handle errors
## Example Usage
**User:** "I have session 7 on my FreeBSD dev machine that needs summarization, but FreeBSD doesn't have Gemini API. Can you summarize it here on my Mac?"
**Assistant (with config):**
1. Checks config: `chronicle config remote_systems.freebsd.hostname`
2. Finds: `chandlerhardy-dev.aws0.pla-net.cc`
3. Announces: "Found FreeBSD config, using chandlerhardy-dev.aws0.pla-net.cc"
4. Runs the command:
```bash
ssh chandlerhardy-dev.aws0.pla-net.cc "/home/chandlerhardy/.local/bin/chronicle export-session 7" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh chandlerhardy-dev.aws0.pla-net.cc "/home/chandlerhardy/.local/bin/chronicle import-summary"
```
5. Confirms: "Session 7 summarized successfully and summary imported back to FreeBSD"
**Assistant (without config):**
1. Checks config: `chronicle config --list | grep remote_systems`
2. No FreeBSD config found
3. Asks: "What's your FreeBSD hostname?"
4. User provides: `chandlerhardy-dev.aws0.pla-net.cc`
5. Asks: "What's the path to chronicle on FreeBSD? (press Enter for default 'chronicle')"
6. User provides: `/home/chandlerhardy/.local/bin/chronicle`
7. Suggests: "I can save this to config for future use. Would you like me to?"
8. Runs the command with provided values
9. If user agrees, saves config for next time
**If one-liner hangs:**
1. Falls back to 3-step workflow
2. Exports to `/tmp/session_7.json`
3. Processes locally → `/tmp/summary.json`
4. Imports summary back to remote
5. Confirms success
## Advanced Usage
### Batch Summarize Multiple Sessions
```bash
# List unsummarized sessions on remote
ssh freebsd "chronicle sessions --limit 50" | grep "No summary"
# For each session ID (7, 8, 9):
for id in 7 8 9; do
echo "Summarizing session $id..."
ssh freebsd "chronicle export-session $id" | \
chronicle import-and-summarize --quiet 2>/dev/null | \
ssh freebsd "chronicle import-summary"
done
```
### Inspect Summary Before Importing
```bash
# Export and summarize
ssh freebsd "chronicle export-session 7" | \
chronicle import-and-summarize --quiet 2>/dev/null > /tmp/summary.json
# Review summary
cat /tmp/summary.json | jq '.summary'
# If satisfied, import
cat /tmp/summary.json | ssh freebsd "chronicle import-summary"
```
### Debug Verbose Output
If you need to see what's happening, remove `--quiet`:
```bash
ssh freebsd "chronicle export-session 7" | chronicle import-and-summarize
# Shows: "Importing session...", "Summarizing...", "Cleaning up...", then JSON
```
**Note:** Without `--quiet`, JSON is NOT at line 1, so it won't pipe cleanly to `import-summary`.
## Related Commands
- `chronicle export-session <id>` - Export session as JSON
- `chronicle import-session` - Import session (permanent, gets new ID)
- `chronicle import-and-summarize` - Import + summarize + auto-cleanup (transient)
- `chronicle import-summary` - Update existing session with summary
- `chronicle session <id>` - View session details and summary
## See Also
- **REMOTE_SUMMARIZE_WORKFLOW.md** - Full workflow documentation with examples
- **tests/test_import_export.py** - 17 tests covering all import/export scenarios
- **chronicle-session-documenter** - Document sessions to Obsidian vault after summarization

303
skills/chronicle-session-documenter/SKILL.md Normal file
View File

@@ -0,0 +1,303 @@
---
name: chronicle-session-documenter
description: Document AI-assisted development sessions to Obsidian vault using Chronicle data. Works with MCP (fastest) or CLI commands (portable). Use when completing a coding session, creating development logs, or maintaining a knowledge base of past work. Automatically creates structured notes with metadata, summaries, and wikilinks.
---
# Chronicle Session Documenter
This skill helps you document development sessions to your Obsidian vault using Chronicle's database. Works with both MCP server (fast, structured) or CLI commands (portable, everywhere).
## Auto-Activation
> **This skill auto-activates!** (Milestone #13)
>
> Prompts like "document session 75" or "export to Obsidian" automatically trigger a recommendation to use this skill. No need to manually load it!
>
> **Trigger patterns:** document session, export to obsidian, save to vault
> **See:** `docs/HOOKS.md` for full details
## When to Use This Skill
Use this skill when:
- A development session has just completed
- User wants to document what was accomplished in a session
- Creating a development log or journal entry
- Building a searchable knowledge base of past work
- Need to link related sessions, commits, or decisions
## How It Works
**Option 1: With MCP (Preferred)**
1. **Query Chronicle** - `mcp__chronicle__get_session_summary(session_id)` → Get structured JSON with full summary
2. **Create Note** - `mcp__obsidian__write_note(...)` → Write directly to Obsidian vault
3. **Link Work** - Use session relationships from JSON to create wikilinks
**Option 2: With CLI (Portable)**
1. **Query Chronicle** - `chronicle session <id>` → Get formatted session details and summary
2. **Parse Output** - Extract summary, files, duration from CLI output
3. **Create Note** - `mcp__obsidian__write_note(...)` OR manually create note file
4. **Link Work** - Use parsed data to create wikilinks
**Decision Tree:**
```
Document session to Obsidian
├─ MCP available? → Use mcp__chronicle__get_session_summary() + mcp__obsidian__write_note()
└─ CLI only? → Use `chronicle session <id>`, parse output, write note
```
**Note**: Summaries are automatically generated in background when session ends (may still be processing for recent sessions)
## Note Structure
Create notes in `Chronicle/Sessions/Session-{id}.md` with this format:
```markdown
---
session_id: {id}
date: "{YYYY-MM-DD}"
started: "{HH:MM AM/PM}"
duration_minutes: {minutes}
ai_tool: "{tool}"
repo: "{repo_name}"
tags: ["chronicle-session", "{ai_tool}", "{topics}"]
---
# Session {id} - {Brief Title}
**Duration:** {duration}
**Repository:** [[{repo_name}]]
**Tool:** {AI Tool Name}
## Summary
{AI-generated summary from Chronicle}
## What Was Accomplished
- {Key accomplishment 1}
- {Key accomplishment 2}
## Key Technical Decisions
- {Decision 1 and rationale}
## Files Created or Modified
- `path/to/file.py` - {what changed}
## Issues & Blockers
- {Any problems encountered}
## Related
- Previous: [[Session-{prev_id}]]
- Commits: [[Commit-{sha}]]
- Repository: [[{repo_name}]]
```
## Workflow Examples
### Option 1: With MCP (Fast, Structured)
**After completing a session:**
```python
# Step 1: Get session data from Chronicle MCP
session_data = mcp__chronicle__get_session_summary(session_id=10)
# Step 2: Extract key information
session_id = session_data["id"]
timestamp = session_data["timestamp"] # "2025-10-24T14:30:00"
tool = session_data["tool"] # "claude-code"
duration = session_data["duration_minutes"] # 45
repo_path = session_data["repo_path"] # "/Users/.../my-project"
summary = session_data["summary"] # AI-generated summary (multi-paragraph)
# Step 3: Format note content
note_content = f"""# Session {session_id} - {brief_title}
**Duration:** {duration} minutes
**Repository:** [[{repo_name}]]
**Tool:** {tool_emoji} {tool_name}
## Summary
{summary}
## What Was Accomplished
- {extracted_accomplishments}
## Key Technical Decisions
- {extracted_decisions}
## Files Created or Modified
- {extracted_files}
## Issues & Blockers
- {extracted_blockers}
## Related
- Previous: [[Session-{prev_id}]]
"""
# Step 4: Prepare frontmatter
frontmatter = {
"session_id": session_id,
"date": "2025-10-24",
"started": "14:30",
"duration_minutes": duration,
"ai_tool": tool,
"repo": repo_name,
"tags": ["chronicle-session", tool, "feature-work"]
}
# Step 5: Write to Obsidian vault (if MCP available)
mcp__obsidian__write_note(
path="Chronicle/Sessions/Session-10.md",
content=note_content,
frontmatter=frontmatter,
mode="overwrite"
)
```
### Option 2: With CLI (Portable, No MCP Required)
**After completing a session:**
```bash
# Step 1: Get session data from Chronicle CLI
chronicle session 10 > /tmp/session_10.txt
# Step 2: Parse the output to extract:
# - Session ID, timestamp, tool, duration
# - Repository path
# - AI-generated summary
# - Files mentioned
# - Keywords/tags
# Step 3: Create note content using parsed data
# (Similar structure to MCP approach above)
# Step 4: If Obsidian MCP available, use it to write note:
# mcp__obsidian__write_note(...)
#
# OR manually create file in Obsidian vault:
# Write to ~/Documents/Obsidian/Chronicle/Sessions/Session-10.md
```
**Note**: CLI approach requires parsing Chronicle's formatted output, which is less elegant but fully portable to any system with Chronicle installed.
## Example Usage
**User:** "Can you document session 10 to my Obsidian vault?"
**Assistant (with MCP):**
1. Calls `mcp__chronicle__get_session_summary(session_id=10)`
2. Parses structured JSON to extract accomplishments, decisions, files, blockers
3. Creates structured Markdown content with wikilinks
4. Calls `mcp__obsidian__write_note(...)` to save to vault
5. Confirms: "Documented Session 10 to Chronicle/Sessions/Session-10.md"
**Assistant (without MCP):**
1. Runs `chronicle session 10` to get formatted output
2. Parses CLI output to extract summary and metadata
3. Creates structured Markdown content with wikilinks
4. Either uses `mcp__obsidian__write_note(...)` if available, or creates file manually
5. Confirms: "Documented Session 10 to Chronicle/Sessions/Session-10.md"
## Tools to Use (MCP or CLI)
### Chronicle Database Operations
**MCP Approach (Preferred):**
- `mcp__chronicle__get_session_summary(session_id)` - Get full session details with AI summary
- `mcp__chronicle__get_sessions(limit, days, tool, repo_path)` - List recent sessions to find session ID
- `mcp__chronicle__search_sessions(query, limit)` - Search for sessions by keyword
- `mcp__chronicle__get_commits(repo_path, days, limit)` - Get related commits for linking
- `mcp__chronicle__get_sessions_summaries(session_ids)` - Batch get summaries (up to 20 at once)
**CLI Alternatives:**
- `chronicle session <id>` - Get session details with summary
- `chronicle sessions --limit 10` - List recent sessions
- `chronicle search "keyword" --limit 10` - Search sessions
- `chronicle show today` - Get commits for linking
### Obsidian Vault Operations
**MCP Approach (Preferred):**
- `mcp__obsidian__write_note(path, content, frontmatter, mode)` - Write note to vault
- `mcp__obsidian__read_note(path)` - Check if note already exists (optional)
- `mcp__obsidian__list_directory(path)` - List existing session notes (optional)
**Manual Alternative (No MCP):**
- Create file directly: `~/Documents/Obsidian/<vault>/Chronicle/Sessions/Session-<id>.md`
- Write YAML frontmatter + markdown content manually
## Tips
- **Summary generation is automatic** - Summarization starts in background immediately when session ends (may take a few minutes for large sessions)
- **Parse summaries intelligently** - AI summaries often have sections like "Accomplishments:", "Technical Decisions:", "Issues/Blockers:"
- **Use wikilinks** - Link to `[[Session-{id}]]`, `[[{repo_name}]]`, `[[Commit-{short_sha}]]` for navigation
- **Extract repo name** - Parse from `repo_path`: `/Users/.../my-app` → `my-app`
- **Handle missing data** - Some sessions may not have summaries yet (still processing in background), or durations (still running)
- **Batch document** - Use `get_sessions()` to find recent sessions, then document each in loop
- **Check existing notes** - Use `read_note()` to avoid overwriting manually edited notes (ask user first)
- **Tool emojis** - Use 🎯 for claude-code, ✨ for gemini-cli, 🔮 for qwen-cli
- **Frontmatter tags** - Always include `["chronicle-session", "{tool}", ...]` for filtering in Obsidian
- **Date formatting** - Parse ISO timestamp `2025-10-24T14:30:00` → date: "2025-10-24", started: "14:30"
## Common Patterns
### Document Today's Sessions
**With MCP:**
```python
# Get today's sessions
sessions = mcp__chronicle__get_sessions(days=1, limit=20)
# Document each to vault
for session in sessions:
if session["is_session"]: # Only full sessions, not one-shots
document_to_vault(session["id"])
```
**With CLI:**
```bash
# List today's sessions
chronicle sessions --days 1 --limit 20
# Manually document each one
chronicle session 10 # View details
# Parse and create Obsidian note
```
### Document Specific Session
**With MCP:**
```python
# Direct documentation
session = mcp__chronicle__get_session_summary(session_id=10)
# Create note from structured data
```
**With CLI:**
```bash
# Get session details
chronicle session 10
# Parse output and create note
```
### Find and Document Sessions About a Topic
**With MCP:**
```python
# Search first
results = mcp__chronicle__search_sessions(query="authentication", limit=5)
# Document each match
for result in results:
document_to_vault(result["id"])
```
**With CLI:**
```bash
# Search for sessions
chronicle search "authentication" --limit 5
# Document each match
chronicle session <id>
# Create note from parsed output
```

225
skills/chronicle-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,225 @@
---
name: chronicle-workflow
description: Complete workflow for tracking development work with Chronicle - session recording, git tracking, AI summarization, and Obsidian documentation. Works with CLI commands (portable) or MCP tools (faster). Use when starting a new development session, setting up project tracking, or when user wants comprehensive session management.
---
# Chronicle Workflow
This skill guides you through the complete Chronicle workflow for tracking and documenting development work. Primarily uses CLI commands for portability, with optional MCP tools for faster programmatic access.
## Auto-Activation
> **This skill auto-activates!** (Milestone #13)
>
> Prompts like "start a new session" or "is this tracked?" automatically trigger this skill. No manual loading needed!
>
> **Trigger patterns:** start session, is this tracked, chronicle workflow, setup
> **See:** `docs/HOOKS.md` for full details
## When to Use This Skill
Use this skill when:
- User is starting a new development session
- Setting up Chronicle for the first time
- Want to ensure all work is being tracked
- Need guidance on Chronicle best practices
- Building a comprehensive development knowledge base
## Complete Workflow
### 1. Session Start (If Not Already Tracking)
**Check if in Chronicle session:**
- Current session is likely NOT being tracked unless started with `chronicle start claude`
- To track current work, user must exit and restart with Chronicle
**Guide user:**
```bash
# Exit current session
exit
# Start new Chronicle-tracked session
chronicle start claude
# Or for other tools:
chronicle start gemini
```
**Important:** Chronicle sessions must be started explicitly - they don't auto-track.
### 2. During Development
**Best Practices:**
- Work naturally - Chronicle captures everything automatically
- Make frequent git commits with descriptive messages
- Chronicle links commits to sessions automatically (±30 min window)
**Available Commands (don't interrupt work to run these):**
```bash
chronicle sessions # List recent sessions
chronicle show today # See today's commits
chronicle timeline today # Combined view
```
### 3. Session End
**Automatic on Exit:**
- Full transcript captured to `~/.ai-session/sessions/session_N.log`
- Metadata saved (duration, timestamp, repo)
- Session record created in database
**What happens:**
```
📊 Session #{id} complete! Duration: {minutes} minutes
💾 Full transcript saved
✨ Use 'chronicle session {id}' to view
```
### 4. Post-Session Documentation
**Generate Summary (Automatic on first view):**
```bash
# View session and auto-generate summary
chronicle session {id}
# For very large sessions (>50K lines)
chronicle summarize-chunked {id}
```
**Document to Obsidian:**
Use the `chronicle-session-documenter` skill or manually:
```
"Document session {id} to my Obsidian vault"
```
### 5. Retrieval & Context
**Find Past Work:**
Use the `chronicle-context-retriever` skill:
```
"How did I implement authentication last time?"
"What was the blocker with database migrations?"
"Show me all work on the API refactor"
```
**Browse Sessions (CLI):**
```bash
# Filter by repo
chronicle sessions --repo /path/to/project
# View timeline
chronicle timeline week
# Search sessions
chronicle search "authentication" --limit 5
```
**Browse Sessions (MCP - if available):**
```python
# Faster programmatic access
sessions = mcp__chronicle__get_sessions(repo_path="/path/to/project", limit=20)
results = mcp__chronicle__search_sessions(query="authentication", limit=5)
```
## Workflow Patterns
### Pattern 1: Quick Feature Work
```
1. chronicle start claude
2. [Make changes, commit]
3. exit
4. [Summary auto-generates on next view]
```
### Pattern 2: Multi-Session Project
```
1. chronicle start claude (Day 1)
2. [Work, commit]
3. exit
4. Document to Obsidian
5. chronicle start claude (Day 2)
6. "What did I do yesterday?" (retrieves context)
7. [Continue work]
```
### Pattern 3: Research & Context
```
1. "Show me all sessions about X" (context retriever)
2. Review past approaches and decisions
3. chronicle start claude
4. [Implement with informed approach]
```
## Multi-Project Tracking
**Automatic Detection:**
- Sessions detect working directory and git repo
- Stored in database for filtering
**Filter by Project:**
```bash
chronicle sessions --repo /path/to/project
chronicle timeline today --repo /path/to/project
chronicle summarize today --repo /path/to/project
```
## Key Features to Highlight
### Chunked Summarization
- Handles sessions of **unlimited size**
- Tested with 83,000+ line sessions
- Uses rolling summaries (10,000 lines/chunk)
- No rate limit issues
### Obsidian Integration
- Full MCP server integration
- Create structured session notes
- Search past work
- Build knowledge graph
- Wikilinks between sessions/commits/repos
### Local-First
- Everything stored locally (`~/.ai-session/`)
- SQLite database
- No data leaves your machine (except AI summarization)
## Common Questions
**Q: "Is this session being tracked?"**
A: Only if started with `chronicle start claude`. Must be explicit.
**Q: "Can I track a session retroactively?"**
A: No - must start with Chronicle from the beginning.
**Q: "How do I see what I did yesterday?"**
A: Use `chronicle timeline yesterday` or search Obsidian vault
**Q: "How do I link commits to sessions?"**
A: Automatic! Commits within ±30 minutes of session are linked.
## Database Location
All data stored at:
```
~/.ai-session/
├── sessions.db # Main database
├── sessions/
│ ├── session_N.log # Transcripts
│ └── session_N.meta # Metadata
└── config.yaml # Configuration
```
## Pro Tips
1. **Start Chronicle early** - Can't retroactively track
2. **Commit frequently** - Better session-commit linking
3. **Document important sessions** - Build knowledge base in Obsidian
4. **Search before building** - Use context retriever to avoid repeating work
5. **Use tags in Obsidian** - Makes finding past work easier
6. **Review summaries** - Helps remember key decisions
## Integration with Other Skills
- Use `chronicle-session-documenter` after completing sessions
- Use `chronicle-context-retriever` when starting related work
- Combine with git workflows for comprehensive tracking