Context Progress

Update Project Progress

This skill guides you through updating the context-progress branch to reflect current project status.

When to Use

Use this skill when:

• Completing a significant task or milestone
• Starting new work that should be tracked
• Updating project status after a development session
• The user requests to "update progress" or "track status"

Why context-progress Branch?

The context-progress branch uses a unique approach:

• Stable Reference: CLAUDE.md references the branch name, not a commit hash
• Mutable State: Progress changes frequently, so we amend one commit rather than creating many
• No Hash Updates: Avoids needing to update CLAUDE.md constantly
• Clean History: Keeps the main branch clean from progress tracking commits

Auto-Extraction (Recommended)

The auto-extraction feature automatically generates structured progress content from your git history, inspired by the /compact tool's extraction patterns.

Quick Start

# Preview what will be extracted (no changes made)
~/.claude/plugins/context-commit/hooks/update-progress.sh --preview

# Update with auto-extraction (opens editor for review)
~/.claude/plugins/context-commit/hooks/update-progress.sh

# Update without editor (for CI/automation)
CONTEXT_SKIP_EDIT=1 ~/.claude/plugins/context-commit/hooks/update-progress.sh

What Gets Auto-Extracted

Merge Modes

Control how auto-extracted content merges with existing progress:

# Smart merge (default): preserve your manual "In Progress" and "Planned" edits
CONTEXT_MERGE_MODE=smart ./update-progress.sh

# Replace: use only auto-extracted content
CONTEXT_MERGE_MODE=replace ./update-progress.sh

# Append: add auto-extracted as new section
CONTEXT_MERGE_MODE=append ./update-progress.sh

Auto-Extracted Output Format

[CONTEXT] Project Progress

Auto-extracted progress as of 2026-01-12 15:30

## Recent Commits

### Features
- [x] [abc1234] Add user authentication endpoint
- [x] [def5678] Implement dark mode toggle

### Fixes
- [x] [ghi9012] Fix race condition in data loader

### Tests
- [x] [jkl3456] Add unit tests for auth module

## File Changes

M  src/auth/login.swift
A  src/ui/darkmode.swift
D  src/deprecated/oldauth.swift

## Issues Resolved

- [ghi9012] Fix race condition in data loader

## Key Code References

- src/auth/login.swift: func authenticate
- src/ui/darkmode.swift: class ThemeManager

## In Progress

- [ ] (preserved from your previous edits)

## Planned

- [ ] (preserved from your previous edits)

Standalone Extraction

For programmatic use or custom workflows:

# Generate markdown output
~/.claude/plugins/context-commit/hooks/auto-extract-progress.sh markdown

# Generate JSON output
~/.claude/plugins/context-commit/hooks/auto-extract-progress.sh json

Manual Update Workflow

For cases where auto-extraction isn't suitable, use manual methods:

Method 1: Simple Amend (Recommended)

Use this when the context-progress branch is already on the latest work:

# Switch to context-progress branch
git checkout context-progress

# Amend the progress commit with updated status
git commit --amend

# This opens your editor to update the commit message

# Switch back to main working branch
git checkout master  # or main

Method 2: Rebase and Amend

Use this when you've made new commits on master that should be included in progress:

# Ensure you're on your working branch (master/main)
git checkout master

# Switch to context-progress
git checkout context-progress

# Rebase onto master to include new work
git rebase master

# Amend the progress commit with updated checklist
git commit --amend

# Switch back to master
git checkout master

Method 3: Force Update from Master

Use this to reset context-progress to current master state, then update progress:

# On master after new work is committed
git checkout master

# Force context-progress to match master
git branch -f context-progress master

# Switch to context-progress
git checkout context-progress

# Amend to update progress
git commit --amend

# Back to master
git checkout master

Progress Commit Structure

The progress commit should follow this template:

[CONTEXT] Project Name Progress

This commit tracks the current state of project development.

## Completed ✓

### Category 1
- [x] Completed task 1
- [x] Completed task 2
- [x] Completed task 3

### Category 2
- [x] Another completed task
- [x] More completed work

## In Progress

- [ ] Current task being worked on
- [ ] Another active task

## Planned

- [ ] Future task 1
- [ ] Future task 2
- [ ] Future enhancement

## Metrics (Optional)

- Test Coverage: 85%
- Performance: 1.2ms average
- Build Status: Passing

---
Update this commit via: git commit --amend
Update from master via: git rebase master && git commit --amend

Best Practices

Checklist Guidelines

1. Use Markdown Checkboxes: - [x] for done, - [ ] for pending
2. Group by Category: Organize tasks into logical sections
3. Be Specific: "Implement user authentication" not just "Auth"
4. Include Context: Add enough detail to understand what was done
5. Update Regularly: Keep progress current (daily or per session)

What to Track

Completed Section:

• Features implemented
• Bugs fixed
• Tests added
• Documentation written
• Performance improvements

In Progress Section:

• Current active work (1-3 tasks max)
• Blocked tasks with blockers noted
• Tasks started but not finished

Planned Section:

• Next tasks in the queue
• Future features or improvements
• Technical debt items
• Nice-to-have enhancements

What NOT to Track

• Minute-by-minute changes (too granular)
• Temporary debugging steps
• Work-in-progress that's not committed
• Personal notes (use a separate system)

Updating After Completing Tasks

When you complete tasks, follow this flow:

# 1. On master, do your work and commit normally
git add .
git commit -m "Implement feature X"

# 2. Switch to context-progress
git checkout context-progress

# 3. Rebase to include new work
git rebase master

# 4. Amend the progress commit
git commit --amend
# In editor, move completed tasks from "In Progress" to "Completed ✓"
# Add new tasks to "In Progress" or "Planned"

# 5. Back to master
git checkout master

Reading Current Progress

To view current progress without switching branches:

# View the full progress commit
git log context-progress -1 --format=%B

# Or just the commit message
git show context-progress --format=%B --no-patch

Handling Conflicts

If rebase causes conflicts:

# On context-progress branch after rebase conflict
git status  # See conflicting files

# Resolve conflicts in files
# Then continue rebase
git add .
git rebase --continue

# Amend progress commit
git commit --amend

Sharing Progress

The context-progress branch can be pushed to share status with team:

# Push progress branch
git push origin context-progress --force

# Force is needed because we amend the commit
# This is safe because context-progress is a tracking branch, not a code branch

Warning: Only force-push the context-progress branch, never main/master!

Integration with Claude Sessions

Claude reads progress automatically:

1. CLAUDE.md references context-progress branch
2. On session start, Claude runs git log context-progress -1 --format=%B
3. Claude sees current status and completed work
4. Can pick up where previous session left off

Example Progress Update Session

# Scenario: Just finished implementing authentication

# 1. Commit the work on master
git add .
git commit -m "Implement JWT authentication with refresh tokens"

# 2. Update progress
git checkout context-progress
git rebase master
git commit --amend

# In the editor, update:
# Move "- [ ] Implement authentication" to Completed ✓ section
# Change to "- [x] Implement JWT authentication with refresh tokens"
# Add "- [ ] Add rate limiting to auth endpoints" to Planned

# 3. Return to master
git checkout master

Troubleshooting

Lost context-progress branch:

# Recreate from master
git checkout -b context-progress master
git commit --allow-empty -m "[CONTEXT] Project Progress

## Completed ✓
(Add items here)

## In Progress
(Add items here)

## Planned
(Add items here)
"

Progress out of sync with master:

# Reset context-progress to master, then amend
git branch -f context-progress master
git checkout context-progress
git commit --amend

Want to keep progress history:

# Don't use context-progress for historical tracking
# Instead, create dated snapshot commits:
git commit --allow-empty -m "[PROGRESS-SNAPSHOT] 2026-01-12 Status

(Copy of progress at this point in time)
"

Summary

• context-progress is a special mutable branch for tracking status
• Use git commit --amend to update progress without creating new commits
• Rebase onto master to include new work before amending
• Keep progress current and organized by category
• Claude automatically reads progress on session start

Converted and distributed by TomeVault — claim your Tome and manage your conversions.