Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

project-tracking

Establish the files used to track and manage progress.

pborenstein · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add pborenstein/handoff --skill project-tracking

About this skill


name: project-tracking description: Establish the files used to track and manage progress. allowed-tools: Read, Write, Bash, Glob

Project Tracking Setup

This skill establishes a token-efficient project tracking system for software projects.

System Overview

Token-Efficient Design: Separates hot state (current session) from cold storage (history).

Core Files:

  • CONTEXT.md - Current session state (30-50 lines, read every session)
  • IMPLEMENTATION.md - Phase progress tracker (400-600 lines)
  • DECISIONS.md - Architectural decisions (heading-based, grep-friendly)
  • chronicles/phase-N.md - Detailed session history

Key Benefits:

  • 75% reduction in session pickup tokens (~200 lines → ~50 lines)
  • 45% reduction in chronicle entry size
  • Single file read for session pickup (CONTEXT.md only)

When to Use This Skill

  • New codebases: Set up tracking from day one
  • Existing codebases: Retroactively document project history and establish tracking
  • Legacy projects: Establish tracking on projects that predate this system

Quick Start

PROJECT-TRACKING-REFERENCE.md describes the complete token-efficient documentation system.

For New Projects

  1. Create base structure (no git history to analyze)
  2. Initialize Phase 0 in IMPLEMENTATION.md
  3. Ready to document first session

For Existing Projects (Retroactive)

  1. Use TodoWrite to track setup progress
  2. Analyze project history (see commands below)
  3. Identify phase boundaries based on major milestones
  4. Create documentation structure in order
  5. Document retroactively with appropriate detail level

Step-by-Step Process for Existing Projects

Step 1: Analyze Project History

Run these commands to understand the codebase:

# Full git history
git log --all --oneline --decorate

# Identify major refactors/features
git log --all --oneline --grep="refactor\|feat\|major"

# Check existing documentation
find . -name "*.md" -type f | grep -v node_modules

# Review changelog if exists
cat CHANGELOG.md

# Get commit count and timeline
git log --oneline | wc -l
git log --reverse --format="%ai %s" | head -5
git log --format="%ai %s" | head -5

Step 2: Identify Phase Boundaries

Look for natural breakpoints:

Good phase boundaries:

  • Major architectural refactors ("legendary refactor", "restructure")
  • Feature milestones (v1.0.0, v2.0.0 releases)
  • Significant pivots (monolith → microservices)
  • Technology changes (rewrite in new language)

Aim for 3-6 phases for most projects:

  • Too few: Loses meaningful structure
  • Too many: Fragmented, hard to navigate

Example phase progressions:

  • Foundation → Architecture → Features → Production
  • MVP → Scale → Polish → Maintenance
  • Prototype → Refactor → Features → Optimization

Step 3: Create Files in This Order

Use TodoWrite to track:

1. Create docs/IMPLEMENTATION.md
2. Create docs/DECISIONS.md
3. Create docs/chronicles/ directory
4. Create chronicle files for each phase
5. Create docs/CONTEXT.md (from current phase)
6. Update docs/README.md (if exists)

Note: There is no CHRONICLES.md index file. Use ls docs/chronicles/ for navigation instead.

Step 4: File Creation Details

IMPLEMENTATION.md

For existing projects (token-efficient format):

  • Phase Overview table (all phases)
  • Completed phases: 3-5 bullets each + link to chronicles
    • High-level achievements only
    • Link to chronicles/phase-N.md for details
  • Current phase: Detailed (200-300 lines)
    • Active tasks with checkboxes
    • What's completed so far
    • What's next
  • Future phases: High-level plans (5-10 bullets)

Target size: 400-600 lines

DECISIONS.md

For existing projects (heading-based format):

  • Use heading-based format
  • Each decision is a ### DEC-XXX: Title (YYYY-MM-DD) heading
  • Include: Status, Context, Decision, Alternatives, Consequences
  • Aim for 5-10 decisions for retroactive docs
    • Focus on decisions still relevant today
    • Don't document every minor choice

Extract decisions from:

  • Commit messages mentioning "decision", "choose", "vs"
  • Architecture changes (modular refactor, tech choices)
  • Configuration format choices
  • UI/UX pattern choices

Decision Categories to look for:

  • Architecture (structure, modules, patterns)
  • Configuration (formats, storage)
  • Display/UX (interaction patterns, visual design)
  • Technology (language, framework, library choices)

CONTEXT.md

For existing projects:

  • Create from current phase section in IMPLEMENTATION.md
  • Extract: current focus, active tasks, blockers
  • Get latest commit hash and entry number
  • Keep under 50 lines total

Sections:

  • Frontmatter (phase, updated, last_commit, last_entry)
  • Current Focus (1-2 sentences)
  • Active Tasks (checkboxes)
  • Blockers (if any)
  • Context (3-5 bullets)
  • Next Session (where to pick up)

This file replaces reading ~200 lines from IMPLEMENTATION.md for session pickup.

chronicles/phase-X-name.md

For existing projects (retroactive entries):

Balance detail vs. effort:

  • Older phases (completed long ago):

    • One summary entry per phase
    • High-level "what and why"
    • Light on implementation details
    • Focus on decisions and outcomes
  • Recent phases (last 3-6 months):

    • More detailed entries
    • Can document specific features
    • Include code examples if relevant
  • Current phase:

    • Full detail from this point forward
    • Document each session

Retroactive entry format (slim template):

## Entry N: [Phase Name] (YYYY-MM-DD)

**What**: [1-2 sentences - what was accomplished in this phase]

**Why**: [1-2 sentences - context/motivation]

**How**: [Bullet points - key implementation details, max 5-7 bullets]

- Key change 1
- Key change 2
- Key change 3

**Decisions**: [Optional - only if DEC-XXX made]

- DEC-XXX: [one-line summary, detail in DECISIONS.md]

**Files**: [key
Read the complete source ↗