Use this skill when working with project tracking - creating initiatives, todos, ideas, logging sessions, or recording decisions. Activates when user mentions projects, tasks, initiatives, or planning.
/plugin marketplace add hhopkins95/project-tracker/plugin install project-tracker@project-tracker-mpThis skill inherits all available tools. When active, it can use any tool Claude has access to.
A file-based system for tracking work across Claude Code sessions. The workspace root is defined by $PROJECT_TRACKER_WORKSPACE.
An initiative is a body of work that:
Examples: "Add user authentication", "Refactor database layer", "Build CLI tool"
| Type | When to Use | Scope | Structure |
|---|---|---|---|
| Initiative | Multi-session work with a clear goal | Days to weeks | Folder with tracker, sessions, decisions |
| Todo | Single-session task, standalone | Hours | Single markdown file |
| Idea | Captured thought, not committed to yet | N/A | Single markdown file |
Rule of thumb: If you'll need to "pick up where you left off" in a future session, it's an initiative. If you can finish it now, it's a todo.
Idea → Initiative (backlog) → Initiative (active) → Initiative (completed)
↑ ↓
Todo ←──── (if scope shrinks) ←┘
initiatives/{state}/{slug}/
├── INITIATIVE.md # Required: Goal, scope, completion criteria (static)
├── TRACKER.md # Required: Current status dashboard (updated frequently)
├── sessions/ # Recommended: Work session logs
│ └── YYYY-MM-DD-{description}.md
├── decisions/ # Optional: Architecture Decision Records
│ └── {slug}.md
└── {other}/ # Optional: plans/, research/, notes/, assets/
| Component | Required? | Purpose |
|---|---|---|
INITIATIVE.md | Yes | Defines what and why - the anchor document |
TRACKER.md | Yes | Current status - read this for quick context |
sessions/ | Recommended | History of work sessions |
decisions/ | Optional | Significant architectural decisions |
| Other folders | Optional | Whatever supports the work |
TRACKER.md is the quick-context file. Read this first to understand where an initiative stands without loading full session history.
---
phase: planning | in-progress | testing | blocked | wrapping-up
updated: 'YYYY-MM-DD'
---
# {Initiative Title} - Tracker
## Current Status
One paragraph: What's the current state? What was just completed? What's next?
## Completion Progress
- [x] Criterion 1 (done in session YYYY-MM-DD)
- [ ] Criterion 2 (in progress)
- [ ] Criterion 3
## Active Blockers
- Blocker description → potential resolution
## Next Session
Priority tasks for the next work session:
1. Task 1
2. Task 2
## Recent Activity
| Date | Session | Summary |
|------|---------|---------|
| YYYY-MM-DD | [description](sessions/YYYY-MM-DD-description.md) | What was done |
| YYYY-MM-DD | [description](sessions/YYYY-MM-DD-description.md) | What was done |
## Key Decisions
| Decision | Date | Link |
|----------|------|------|
| Decision title | YYYY-MM-DD | [→](decisions/slug.md) |
After each session:
phase and updated in frontmatterThe tracker should be readable in under 30 seconds - it's a dashboard, not documentation.
TRACKER.md tells you where things standCreate session log: sessions/YYYY-MM-DD-{description}.md
Update tracker: Reflect current state
This creates continuity across Claude sessions without requiring full history reads.
Defines the work. Relatively static - updated when scope changes, not every session.
---
title: Human-Readable Title
description: One-line summary of what this initiative accomplishes
created: 'YYYY-MM-DD'
status: active | backlog | completed
tags:
- tag1
---
# {Title}
## Goal
What this initiative aims to accomplish. Be specific.
## Scope
### In Scope
- Item 1
- Item 2
### Out of Scope
- Item 1 (explicitly excluded)
## Completion Criteria
How we know this is done:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
## Context
Background information, links to related resources, or technical context needed to understand this initiative.
Records what happened in a work session.
---
date: 'YYYY-MM-DD'
---
# {Brief Description}
## Completed
- [x] Task 1
- [x] Task 2
## Decisions Made
- Decision 1: rationale
- Decision 2: rationale
## Blockers Encountered
- Blocker: how it was resolved (or not)
## Next Session
- [ ] Task 1
- [ ] Task 2
## Notes
Any additional context, code snippets, or observations.
For significant decisions that need preserved rationale. Don't create these for every small choice.
When to create a decision record:
---
date: 'YYYY-MM-DD'
status: proposed | accepted | superseded
---
# {Decision Title}
## Context
What situation prompted this decision.
## Decision
What was decided.
## Rationale
Why this approach was chosen.
## Alternatives Considered
- Alternative 1: Why not chosen
- Alternative 2: Why not chosen
Quick standalone task. If it grows, promote to initiative.
---
title: Todo Title
created: 'YYYY-MM-DD'
priority: low | medium | high
---
# {Title}
What needs to be done.
## Notes
Additional context if needed.
Captured thought. Low friction - just get it down.
---
title: Idea Title
created: 'YYYY-MM-DD'
---
# {Title}
The idea.
## Why Valuable
Why this might be worth doing.
## Initial Thoughts
- Thought 1
- Thought 2
$PROJECT_TRACKER_WORKSPACE/
├── initiatives/
│ ├── active/ # Currently being worked on (ideally 1)
│ │ └── {slug}/
│ ├── backlog/ # Planned for future
│ │ └── {slug}/
│ └── completed/ # Finished work (reference)
│ └── {slug}/
├── todos/ # Quick standalone tasks
│ └── {slug}.md
└── ideas/ # Captured ideas
└── {slug}.md
initiatives/backlog/{slug}/INITIATIVE.md with goal, scope, completion criteriaTRACKER.md with initial statussessions/ directorybacklog/{slug}/ → active/{slug}/status in INITIATIVE.md frontmatterphase in TRACKER.mdsessions/YYYY-MM-DD-{description}.mdTRACKER.md with current statusactive/{slug}/ → completed/{slug}/status to completedbacklog/INITIATIVE.mdTRACKER.mdkebab-case (lowercase, hyphens)YYYY-MM-DDYYYY-MM-DD-{brief-description}.md